NetworkPkg/HttpBootDxe/HttpBootDxe.h

   1 /** @file
   2   UEFI HTTP boot driver's private data structure and interfaces declaration.
   3
   4 Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
   5 (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
  23 //
  24 // Libraries
  25 //
  26 #include <Library/UefiBootServicesTableLib.h>
  27 #include <Library/MemoryAllocationLib.h>
  28 #include <Library/BaseLib.h>
  29 #include <Library/UefiLib.h>
  30 #include <Library/DevicePathLib.h>
  31 #include <Library/DebugLib.h>
  32 #include <Library/NetLib.h>
  33 #include <Library/HttpLib.h>
  34
  35 //
  36 // UEFI Driver Model Protocols
  37 //
  38 #include <Protocol/DriverBinding.h>
  39 #include <Protocol/ComponentName2.h>
  40 #include <Protocol/ComponentName.h>
  41
  42 //
  43 // Consumed Protocols
  44 //
  45 #include <Protocol/NetworkInterfaceIdentifier.h>
  46 #include <Protocol/Dhcp4.h>
  47 #include <Protocol/Dhcp6.h>
  48 #include <Protocol/Dns6.h>
  49 #include <Protocol/Http.h>
  50 #include <Protocol/Ip4Config2.h>
  51 #include <Protocol/Ip6Config.h>
  52 //
  53 // Produced Protocols
  54 //
  55 #include <Protocol/LoadFile.h>
  56
  57 //
  58 // Driver Version
  59 //
  60 #define HTTP_BOOT_DXE_VERSION  0xa
  61
  62 //
  63 // Protocol instances
  64 //
  65 extern EFI_DRIVER_BINDING_PROTOCOL  gHttpBootDxeDriverBinding;
  66 extern EFI_COMPONENT_NAME2_PROTOCOL gHttpBootDxeComponentName2;
  67 extern EFI_COMPONENT_NAME_PROTOCOL  gHttpBootDxeComponentName;
  68
  69 //
  70 // Private data structure
  71 //
  72 typedef struct _HTTP_BOOT_PRIVATE_DATA      HTTP_BOOT_PRIVATE_DATA;
  73 typedef struct _HTTP_BOOT_VIRTUAL_NIC       HTTP_BOOT_VIRTUAL_NIC;
  74
  75 //
  76 // Include files with internal function prototypes
  77 //
  78 #include "HttpBootComponentName.h"
  79 #include "HttpBootDhcp4.h"
  80 #include "HttpBootDhcp6.h"
  81 #include "HttpBootImpl.h"
  82 #include "HttpBootSupport.h"
  83 #include "HttpBootClient.h"
  84
  85 typedef union {
  86   HTTP_BOOT_DHCP4_PACKET_CACHE              Dhcp4;
  87   HTTP_BOOT_DHCP6_PACKET_CACHE              Dhcp6;
  88 } HTTP_BOOT_DHCP_PACKET_CACHE;
  89
  90 struct _HTTP_BOOT_VIRTUAL_NIC {
  91   UINT32                                    Signature;
  92   EFI_HANDLE                                Controller;
  93   EFI_LOAD_FILE_PROTOCOL                    LoadFile;
  94   EFI_DEVICE_PATH_PROTOCOL                  *DevicePath;
  95   HTTP_BOOT_PRIVATE_DATA                    *Private;
  96 };
  97
  98 struct _HTTP_BOOT_PRIVATE_DATA {
  99   UINT32                                    Signature;
 100   EFI_HANDLE                                Controller;
 101   EFI_HANDLE                                Image;
 102
 103   HTTP_BOOT_VIRTUAL_NIC                     *Ip4Nic;
 104   HTTP_BOOT_VIRTUAL_NIC                     *Ip6Nic;
 105
 106   //
 107   // Cousumed children
 108   //
 109   EFI_HANDLE                                Ip6Child;
 110   EFI_HANDLE                                Dhcp4Child;
 111   EFI_HANDLE                                Dhcp6Child;
 112   HTTP_IO                                   HttpIo;
 113   BOOLEAN                                   HttpCreated;
 114
 115   //
 116   // Consumed protocol
 117   //
 118   EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL *Nii;
 119   EFI_IP6_PROTOCOL                          *Ip6;
 120   EFI_IP4_CONFIG2_PROTOCOL                  *Ip4Config2;
 121   EFI_IP6_CONFIG_PROTOCOL                   *Ip6Config;
 122   EFI_DHCP4_PROTOCOL                        *Dhcp4;
 123   EFI_DHCP6_PROTOCOL                        *Dhcp6;
 124   EFI_DEVICE_PATH_PROTOCOL                  *ParentDevicePath;
 125
 126
 127   //
 128   // Produced protocol
 129   //
 130   EFI_LOAD_FILE_PROTOCOL                    LoadFile;
 131   EFI_DEVICE_PATH_PROTOCOL                  *DevicePath;
 132   UINT32                                    Id;
 133
 134   //
 135   // Mode data
 136   //
 137   BOOLEAN                                   UsingIpv6;
 138   BOOLEAN                                   Started;
 139   EFI_IP_ADDRESS                            StationIp;
 140   EFI_IP_ADDRESS                            SubnetMask;
 141   EFI_IP_ADDRESS                            GatewayIp;
 142   EFI_IP_ADDRESS                            ServerIp;
 143   UINT16                                    Port;
 144   CHAR8                                     *BootFileUri;
 145   VOID                                      *BootFileUriParser;
 146   UINTN                                     BootFileSize;
 147   BOOLEAN                                   NoGateway;
 148
 149   //
 150   // Cached HTTP data
 151   //
 152   LIST_ENTRY                                CacheList;
 153
 154   //
 155   // Cached DHCP offer
 156   //
 157   // OfferIndex records the index of DhcpOffer[] buffer, and OfferCount records the num of each type of offer.
 158   //
 159   // It supposed that
 160   //
 161   //   OfferNum:    8
 162   //   OfferBuffer: [ProxyNameUri, DhcpNameUri, DhcpIpUri, ProxyNameUri, ProxyIpUri, DhcpOnly, DhcpIpUri, DhcpNameUriDns]
 163   //   (OfferBuffer is 0-based.)
 164   //
 165   // And assume that (DhcpIpUri is the first priority actually.)
 166   //
 167   //   SelectIndex:     5
 168   //   SelectProxyType: HttpOfferTypeProxyIpUri
 169   //   (SelectIndex is 1-based, and 0 means no one is selected.)
 170   //
 171   // So it should be
 172   //
 173   //                 DhcpIpUri  DhcpNameUriDns  DhcpDns  DhcpOnly  ProxyNameUri  ProxyIpUri  DhcpNameUri
 174   //   OfferCount:  [       2,              1,       0,        1,            2,          1,            1]
 175   //
 176   //   OfferIndex: {[       2,              7,       0,        5,            0,         *4,            1]
 177   //                [       6,              0,       0,        0,            3,          0,            0]
 178   //                [       0,              0,       0,        0,            0,          0,            0]
 179   //                ...                                                                                 ]}
 180   //   (OfferIndex is 0-based.)
 181   //
 182   //
 183   UINT32                                    SelectIndex;
 184   UINT32                                    SelectProxyType;
 185   HTTP_BOOT_DHCP_PACKET_CACHE               OfferBuffer[HTTP_BOOT_OFFER_MAX_NUM];
 186   UINT32                                    OfferNum;
 187   UINT32                                    OfferCount[HttpOfferTypeMax];
 188   UINT32                                    OfferIndex[HttpOfferTypeMax][HTTP_BOOT_OFFER_MAX_NUM];
 189 };
 190
 191 #define HTTP_BOOT_PRIVATE_DATA_SIGNATURE          SIGNATURE_32 ('H', 'B', 'P', 'D')
 192 #define HTTP_BOOT_VIRTUAL_NIC_SIGNATURE           SIGNATURE_32 ('H', 'B', 'V', 'N')
 193 #define HTTP_BOOT_PRIVATE_DATA_FROM_LOADFILE(a)   CR (a, HTTP_BOOT_PRIVATE_DATA, LoadFile, HTTP_BOOT_PRIVATE_DATA_SIGNATURE)
 194 #define HTTP_BOOT_PRIVATE_DATA_FROM_ID(a)         CR (a, HTTP_BOOT_PRIVATE_DATA, Id, HTTP_BOOT_PRIVATE_DATA_SIGNATURE)
 195 #define HTTP_BOOT_VIRTUAL_NIC_FROM_LOADFILE(a)    CR (a, HTTP_BOOT_VIRTUAL_NIC, LoadFile, HTTP_BOOT_VIRTUAL_NIC_SIGNATURE)
 196 extern EFI_LOAD_FILE_PROTOCOL               gHttpBootDxeLoadFile;
 197
 198 /**
 199   Tests to see if this driver supports a given controller. If a child device is provided,
 200   it further tests to see if this driver supports creating a handle for the specified child device.
 201
 202   This function checks to see if the driver specified by This supports the device specified by
 203   ControllerHandle. Drivers will typically use the device path attached to
 204   ControllerHandle and/or the services from the bus I/O abstraction attached to
 205   ControllerHandle to determine if the driver supports ControllerHandle. This function
 206   may be called many times during platform initialization. In order to reduce boot times, the tests
 207   performed by this function must be very small, and take as little time as possible to execute. This
 208   function must not change the state of any hardware devices, and this function must be aware that the
 209   device specified by ControllerHandle may already be managed by the same driver or a
 210   different driver. This function must match its calls to AllocatePages() with FreePages(),
 211   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 212   Because ControllerHandle may have been previously started by the same driver, if a protocol is
 213   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 214   to guarantee the state of ControllerHandle is not modified by this function.
 215
 216   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 217   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 218                                    must support a protocol interface that supplies
 219                                    an I/O abstraction to the driver.
 220   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 221                                    parameter is ignored by device drivers, and is optional for bus
 222                                    drivers. For bus drivers, if this parameter is not NULL, then
 223                                    the bus driver must determine if the bus controller specified
 224                                    by ControllerHandle and the child controller specified
 225                                    by RemainingDevicePath are both supported by this
 226                                    bus driver.
 227
 228   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 229                                    RemainingDevicePath is supported by the driver specified by This.
 230   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 231                                    RemainingDevicePath is already being managed by the driver
 232                                    specified by This.
 233   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 234                                    RemainingDevicePath is already being managed by a different
 235                                    driver or an application that requires exclusive access.
 236                                    Currently not implemented.
 237   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 238                                    RemainingDevicePath is not supported by the driver specified by This.
 239 **/
 240 EFI_STATUS
 241 EFIAPI
 242 HttpBootIp4DxeDriverBindingSupported (
 243   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 244   IN EFI_HANDLE                   ControllerHandle,
 245   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 246   );
 247
 248 /**
 249   Starts a device controller or a bus controller.
 250
 251   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 252   As a result, much of the error checking on the parameters to Start() has been moved into this
 253   common boot service. It is legal to call Start() from other locations,
 254   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 255   1. ControllerHandle must be a valid EFI_HANDLE.
 256   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 257      EFI_DEVICE_PATH_PROTOCOL.
 258   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 259      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 260
 261   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 262   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 263                                    must support a protocol interface that supplies
 264                                    an I/O abstraction to the driver.
 265   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 266                                    parameter is ignored by device drivers, and is optional for bus
 267                                    drivers. For a bus driver, if this parameter is NULL, then handles
 268                                    for all the children of Controller are created by this driver.
 269                                    If this parameter is not NULL and the first Device Path Node is
 270                                    not the End of Device Path Node, then only the handle for the
 271                                    child device specified by the first Device Path Node of
 272                                    RemainingDevicePath is created by this driver.
 273                                    If the first Device Path Node of RemainingDevicePath is
 274                                    the End of Device Path Node, no child handle is created by this
 275                                    driver.
 276
 277   @retval EFI_SUCCESS              The device was started.
 278   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 279   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 280   @retval Others                   The driver failded to start the device.
 281
 282 **/
 283 EFI_STATUS
 284 EFIAPI
 285 HttpBootIp4DxeDriverBindingStart (
 286   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 287   IN EFI_HANDLE                   ControllerHandle,
 288   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 289   );
 290
 291 /**
 292   Stops a device controller or a bus controller.
 293
 294   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 295   As a result, much of the error checking on the parameters to Stop() has been moved
 296   into this common boot service. It is legal to call Stop() from other locations,
 297   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 298   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 299      same driver's Start() function.
 300   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 301      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 302      Start() function, and the Start() function must have called OpenProtocol() on
 303      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 304
 305   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 306   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 307                                 support a bus specific I/O protocol for the driver
 308                                 to use to stop the device.
 309   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 310   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 311                                 if NumberOfChildren is 0.
 312
 313   @retval EFI_SUCCESS           The device was stopped.
 314   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 315
 316 **/
 317 EFI_STATUS
 318 EFIAPI
 319 HttpBootIp4DxeDriverBindingStop (
 320   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 321   IN EFI_HANDLE                   ControllerHandle,
 322   IN UINTN                        NumberOfChildren,
 323   IN EFI_HANDLE                   *ChildHandleBuffer OPTIONAL
 324   );
 325
 326 /**
 327   Tests to see if this driver supports a given controller. If a child device is provided,
 328   it further tests to see if this driver supports creating a handle for the specified child device.
 329
 330   This function checks to see if the driver specified by This supports the device specified by
 331   ControllerHandle. Drivers will typically use the device path attached to
 332   ControllerHandle and/or the services from the bus I/O abstraction attached to
 333   ControllerHandle to determine if the driver supports ControllerHandle. This function
 334   may be called many times during platform initialization. In order to reduce boot times, the tests
 335   performed by this function must be very small, and take as little time as possible to execute. This
 336   function must not change the state of any hardware devices, and this function must be aware that the
 337   device specified by ControllerHandle may already be managed by the same driver or a
 338   different driver. This function must match its calls to AllocatePages() with FreePages(),
 339   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 340   Because ControllerHandle may have been previously started by the same driver, if a protocol is
 341   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 342   to guarantee the state of ControllerHandle is not modified by this function.
 343
 344   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 345   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 346                                    must support a protocol interface that supplies
 347                                    an I/O abstraction to the driver.
 348   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 349                                    parameter is ignored by device drivers, and is optional for bus
 350                                    drivers. For bus drivers, if this parameter is not NULL, then
 351                                    the bus driver must determine if the bus controller specified
 352                                    by ControllerHandle and the child controller specified
 353                                    by RemainingDevicePath are both supported by this
 354                                    bus driver.
 355
 356   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 357                                    RemainingDevicePath is supported by the driver specified by This.
 358   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 359                                    RemainingDevicePath is already being managed by the driver
 360                                    specified by This.
 361   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 362                                    RemainingDevicePath is already being managed by a different
 363                                    driver or an application that requires exclusive access.
 364                                    Currently not implemented.
 365   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 366                                    RemainingDevicePath is not supported by the driver specified by This.
 367 **/
 368 EFI_STATUS
 369 EFIAPI
 370 HttpBootIp6DxeDriverBindingSupported (
 371   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 372   IN EFI_HANDLE                   ControllerHandle,
 373   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 374   );
 375
 376 /**
 377   Starts a device controller or a bus controller.
 378
 379   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 380   As a result, much of the error checking on the parameters to Start() has been moved into this
 381   common boot service. It is legal to call Start() from other locations,
 382   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 383   1. ControllerHandle must be a valid EFI_HANDLE.
 384   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 385      EFI_DEVICE_PATH_PROTOCOL.
 386   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 387      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 388
 389   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 390   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 391                                    must support a protocol interface that supplies
 392                                    an I/O abstraction to the driver.
 393   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 394                                    parameter is ignored by device drivers, and is optional for bus
 395                                    drivers. For a bus driver, if this parameter is NULL, then handles
 396                                    for all the children of Controller are created by this driver.
 397                                    If this parameter is not NULL and the first Device Path Node is
 398                                    not the End of Device Path Node, then only the handle for the
 399                                    child device specified by the first Device Path Node of
 400                                    RemainingDevicePath is created by this driver.
 401                                    If the first Device Path Node of RemainingDevicePath is
 402                                    the End of Device Path Node, no child handle is created by this
 403                                    driver.
 404
 405   @retval EFI_SUCCESS              The device was started.
 406   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 407   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 408   @retval Others                   The driver failded to start the device.
 409
 410 **/
 411 EFI_STATUS
 412 EFIAPI
 413 HttpBootIp6DxeDriverBindingStart (
 414   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 415   IN EFI_HANDLE                   ControllerHandle,
 416   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 417   );
 418
 419 /**
 420   Stops a device controller or a bus controller.
 421
 422   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 423   As a result, much of the error checking on the parameters to Stop() has been moved
 424   into this common boot service. It is legal to call Stop() from other locations,
 425   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 426   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 427      same driver's Start() function.
 428   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 429      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 430      Start() function, and the Start() function must have called OpenProtocol() on
 431      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 432
 433   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 434   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 435                                 support a bus specific I/O protocol for the driver
 436                                 to use to stop the device.
 437   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 438   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 439                                 if NumberOfChildren is 0.
 440
 441   @retval EFI_SUCCESS           The device was stopped.
 442   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 443
 444 **/
 445 EFI_STATUS
 446 EFIAPI
 447 HttpBootIp6DxeDriverBindingStop (
 448   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 449   IN EFI_HANDLE                   ControllerHandle,
 450   IN UINTN                        NumberOfChildren,
 451   IN EFI_HANDLE                   *ChildHandleBuffer OPTIONAL
 452   );
 453 #endif