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 This program and the accompanying materials are licensed and made available under
   6 the terms and conditions of the BSD License that accompanies this distribution.
   7 The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php.
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __EFI_HTTP_BOOT_DXE_H__
  16 #define __EFI_HTTP_BOOT_DXE_H__
  17
  18 #include <Uefi.h>
  19
  20 //
  21 // Libraries
  22 //
  23 #include <Library/UefiBootServicesTableLib.h>
  24 #include <Library/MemoryAllocationLib.h>
  25 #include <Library/BaseLib.h>
  26 #include <Library/UefiLib.h>
  27 #include <Library/DevicePathLib.h>
  28 #include <Library/DebugLib.h>
  29 #include <Library/NetLib.h>
  30 #include <Library/HttpLib.h>
  31
  32 //
  33 // UEFI Driver Model Protocols
  34 //
  35 #include <Protocol/DriverBinding.h>
  36 #include <Protocol/ComponentName2.h>
  37 #include <Protocol/ComponentName.h>
  38
  39 //
  40 // Consumed Protocols
  41 //
  42 #include <Protocol/NetworkInterfaceIdentifier.h>
  43 #include <Protocol/Dhcp4.h>
  44 #include <Protocol/Http.h>
  45 #include <Protocol/Ip4Config2.h>
  46
  47 //
  48 // Produced Protocols
  49 //
  50 #include <Protocol/LoadFile.h>
  51
  52 //
  53 // Driver Version
  54 //
  55 #define HTTP_BOOT_DXE_VERSION  0xa
  56
  57 //
  58 // Protocol instances
  59 //
  60 extern EFI_DRIVER_BINDING_PROTOCOL  gHttpBootDxeDriverBinding;
  61 extern EFI_COMPONENT_NAME2_PROTOCOL gHttpBootDxeComponentName2;
  62 extern EFI_COMPONENT_NAME_PROTOCOL  gHttpBootDxeComponentName;
  63
  64 //
  65 // Private data structure
  66 //
  67 typedef struct _HTTP_BOOT_PRIVATE_DATA      HTTP_BOOT_PRIVATE_DATA;
  68
  69 //
  70 // Include files with internal function prototypes
  71 //
  72 #include "HttpBootComponentName.h"
  73 #include "HttpBootDhcp4.h"
  74 #include "HttpBootImpl.h"
  75 #include "HttpBootSupport.h"
  76 #include "HttpBootClient.h"
  77
  78 typedef union {
  79   HTTP_BOOT_DHCP4_PACKET_CACHE              Dhcp4;
  80 } HTTP_BOOT_DHCP_PACKET_CACHE;
  81
  82 struct _HTTP_BOOT_PRIVATE_DATA {
  83   UINT32                                    Signature;
  84   EFI_HANDLE                                Controller;
  85   EFI_HANDLE                                Image;
  86
  87   //
  88   // Cousumed children
  89   //
  90   EFI_HANDLE                                Dhcp4Child;
  91   HTTP_IO                                   HttpIo;
  92   BOOLEAN                                   HttpCreated;
  93
  94   //
  95   // Consumed protocol
  96   //
  97   EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL *Nii;
  98   EFI_IP4_CONFIG2_PROTOCOL                  *Ip4Config2;
  99   EFI_DHCP4_PROTOCOL                        *Dhcp4;
 100   EFI_DEVICE_PATH_PROTOCOL                  *ParentDevicePath;
 101
 102   //
 103   // Produced children
 104   //
 105   EFI_HANDLE                                ChildHandle;
 106
 107   //
 108   // Produced protocol
 109   //
 110   EFI_LOAD_FILE_PROTOCOL                    LoadFile;
 111   EFI_DEVICE_PATH_PROTOCOL                  *DevicePath;
 112   UINT32                                    Id;
 113
 114   //
 115   // Mode data
 116   //
 117   BOOLEAN                                   UsingIpv6;
 118   BOOLEAN                                   Started;
 119   EFI_IP_ADDRESS                            StationIp;
 120   EFI_IP_ADDRESS                            SubnetMask;
 121   EFI_IP_ADDRESS                            GatewayIp;
 122   UINT16                                    Port;
 123   CHAR8                                     *BootFileUri;
 124   VOID                                      *BootFileUriParser;
 125   UINTN                                     BootFileSize;
 126
 127   //
 128   // Cached HTTP data
 129   //
 130   LIST_ENTRY                                CacheList;
 131
 132   //
 133   // Cached DHCP offer
 134   //
 135   // OfferIndex records the index of DhcpOffer[] buffer, and OfferCount records the num of each type of offer.
 136   //
 137   // It supposed that
 138   //
 139   //   OfferNum:    8
 140   //   OfferBuffer: [ProxyNameUri, DhcpNameUri, DhcpIpUri, ProxyNameUri, ProxyIpUri, DhcpOnly, DhcpIpUri, DhcpNameUriDns]
 141   //   (OfferBuffer is 0-based.)
 142   //
 143   // And assume that (DhcpIpUri is the first priority actually.)
 144   //
 145   //   SelectIndex:     5
 146   //   SelectProxyType: HttpOfferTypeProxyIpUri
 147   //   (SelectIndex is 1-based, and 0 means no one is selected.)
 148   //
 149   // So it should be
 150   //
 151   //                 DhcpIpUri  DhcpNameUriDns  DhcpDns  DhcpOnly  ProxyNameUri  ProxyIpUri  DhcpNameUri
 152   //   OfferCount:  [       2,              1,       0,        1,            2,          1,            1]
 153   //
 154   //   OfferIndex: {[       2,              7,       0,        5,            0,         *4,            1]
 155   //                [       6,              0,       0,        0,            3,          0,            0]
 156   //                [       0,              0,       0,        0,            0,          0,            0]
 157   //                ...                                                                                 ]}
 158   //   (OfferIndex is 0-based.)
 159   //
 160   //
 161   UINT32                                    SelectIndex;
 162   UINT32                                    SelectProxyType;
 163   HTTP_BOOT_DHCP_PACKET_CACHE               OfferBuffer[HTTP_BOOT_OFFER_MAX_NUM];
 164   UINT32                                    OfferNum;
 165   UINT32                                    OfferCount[HttpOfferTypeMax];
 166   UINT32                                    OfferIndex[HttpOfferTypeMax][HTTP_BOOT_OFFER_MAX_NUM];
 167 };
 168
 169 #define HTTP_BOOT_PRIVATE_DATA_SIGNATURE          SIGNATURE_32 ('H', 'B', 'P', 'D')
 170 #define HTTP_BOOT_PRIVATE_DATA_FROM_LOADFILE(a)   CR (a, HTTP_BOOT_PRIVATE_DATA, LoadFile, HTTP_BOOT_PRIVATE_DATA_SIGNATURE)
 171 #define HTTP_BOOT_PRIVATE_DATA_FROM_ID(a)         CR (a, HTTP_BOOT_PRIVATE_DATA, Id, HTTP_BOOT_PRIVATE_DATA_SIGNATURE)
 172
 173 extern EFI_LOAD_FILE_PROTOCOL               gHttpBootDxeLoadFile;
 174
 175 /**
 176   Tests to see if this driver supports a given controller. If a child device is provided,
 177   it further tests to see if this driver supports creating a handle for the specified child device.
 178
 179   This function checks to see if the driver specified by This supports the device specified by
 180   ControllerHandle. Drivers will typically use the device path attached to
 181   ControllerHandle and/or the services from the bus I/O abstraction attached to
 182   ControllerHandle to determine if the driver supports ControllerHandle. This function
 183   may be called many times during platform initialization. In order to reduce boot times, the tests
 184   performed by this function must be very small, and take as little time as possible to execute. This
 185   function must not change the state of any hardware devices, and this function must be aware that the
 186   device specified by ControllerHandle may already be managed by the same driver or a
 187   different driver. This function must match its calls to AllocatePages() with FreePages(),
 188   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 189   Because ControllerHandle may have been previously started by the same driver, if a protocol is
 190   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 191   to guarantee the state of ControllerHandle is not modified by this function.
 192
 193   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 194   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 195                                    must support a protocol interface that supplies
 196                                    an I/O abstraction to the driver.
 197   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 198                                    parameter is ignored by device drivers, and is optional for bus
 199                                    drivers. For bus drivers, if this parameter is not NULL, then
 200                                    the bus driver must determine if the bus controller specified
 201                                    by ControllerHandle and the child controller specified
 202                                    by RemainingDevicePath are both supported by this
 203                                    bus driver.
 204
 205   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 206                                    RemainingDevicePath is supported by the driver specified by This.
 207   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 208                                    RemainingDevicePath is already being managed by the driver
 209                                    specified by This.
 210   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 211                                    RemainingDevicePath is already being managed by a different
 212                                    driver or an application that requires exclusive access.
 213                                    Currently not implemented.
 214   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 215                                    RemainingDevicePath is not supported by the driver specified by This.
 216 **/
 217 EFI_STATUS
 218 EFIAPI
 219 HttpBootIp4DxeDriverBindingSupported (
 220   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 221   IN EFI_HANDLE                   ControllerHandle,
 222   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 223   );
 224
 225 /**
 226   Starts a device controller or a bus controller.
 227
 228   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 229   As a result, much of the error checking on the parameters to Start() has been moved into this
 230   common boot service. It is legal to call Start() from other locations,
 231   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 232   1. ControllerHandle must be a valid EFI_HANDLE.
 233   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 234      EFI_DEVICE_PATH_PROTOCOL.
 235   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 236      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 237
 238   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 239   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 240                                    must support a protocol interface that supplies
 241                                    an I/O abstraction to the driver.
 242   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 243                                    parameter is ignored by device drivers, and is optional for bus
 244                                    drivers. For a bus driver, if this parameter is NULL, then handles
 245                                    for all the children of Controller are created by this driver.
 246                                    If this parameter is not NULL and the first Device Path Node is
 247                                    not the End of Device Path Node, then only the handle for the
 248                                    child device specified by the first Device Path Node of
 249                                    RemainingDevicePath is created by this driver.
 250                                    If the first Device Path Node of RemainingDevicePath is
 251                                    the End of Device Path Node, no child handle is created by this
 252                                    driver.
 253
 254   @retval EFI_SUCCESS              The device was started.
 255   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 256   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 257   @retval Others                   The driver failded to start the device.
 258
 259 **/
 260 EFI_STATUS
 261 EFIAPI
 262 HttpBootIp4DxeDriverBindingStart (
 263   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 264   IN EFI_HANDLE                   ControllerHandle,
 265   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 266   );
 267
 268 /**
 269   Stops a device controller or a bus controller.
 270
 271   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 272   As a result, much of the error checking on the parameters to Stop() has been moved
 273   into this common boot service. It is legal to call Stop() from other locations,
 274   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 275   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 276      same driver's Start() function.
 277   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 278      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 279      Start() function, and the Start() function must have called OpenProtocol() on
 280      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 281
 282   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 283   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 284                                 support a bus specific I/O protocol for the driver
 285                                 to use to stop the device.
 286   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 287   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 288                                 if NumberOfChildren is 0.
 289
 290   @retval EFI_SUCCESS           The device was stopped.
 291   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 292
 293 **/
 294 EFI_STATUS
 295 EFIAPI
 296 HttpBootIp4DxeDriverBindingStop (
 297   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 298   IN EFI_HANDLE                   ControllerHandle,
 299   IN UINTN                        NumberOfChildren,
 300   IN EFI_HANDLE                   *ChildHandleBuffer OPTIONAL
 301   );
 302
 303 #endif