StdLib/SocketDxe/DriverBinding.c

   1 /** @file
   2   Implement the driver binding protocol for the socket layer.
   3
   4   Copyright (c) 2011, Intel Corporation
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  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   \section NetworkAdapterManagement Network Adapter Management
  15   Network adapters may come and go over the life if a system running
  16   UEFI.  The SocketDxe driver uses the driver binding API to manage
  17   the connections to network adapters.
  18
  19   The ::DriverSupported routine selects network adapters that the
  20   socket layer is not using.  This determination by the lack of the
  21   tag GUID associated with the network protocol in the
  22   ::cEslSocketBinding array.  The selected network adapters are
  23   passed to the ::DriverStart routine.
  24
  25   The ::DriverStart routine calls the ::EslServiceConnect routine
  26   to create an ::ESL_SERVICE structure to manage the network adapter
  27   for the socket layer.  EslServiceConnect also installs the tag
  28   GUID on the network adapter to prevent future calls from
  29   ::DriverSupported.  EslService also calls the network specific
  30   initialization routine listed in ESL_SOCKET_BINDING::pfnInitialize
  31   field of the ::cEslSocketBinding entry.
  32
  33   The ::DriverStop routine calls the ::EslServiceDisconnect routine
  34   to undo the work done by ::DriverStart.  The socket layer must break
  35   the active network connections, then remove the tag GUIDs from the
  36   controller handle and free ::ESL_SERVICE structure.
  37
  38 **/
  39
  40 #include "Socket.h"
  41
  42 /**
  43   Verify the controller type
  44
  45   This routine walks the cEslSocketBinding array to determines if
  46   the controller is a network adapter by supporting any of the
  47   network protocols required by the sockets layer.  If so, the
  48   routine verifies that the socket layer is not already using the
  49   support by looking for the tag GUID listed in the corresponding
  50   array entry.  The controller handle is passed to the ::DriverStart
  51   routine if sockets can use the network adapter.
  52   See the \ref NetworkAdapterManagement section.
  53
  54   This routine is called by the UEFI driver framework during connect
  55   processing.
  56
  57   @param [in] pThis                Protocol instance pointer.
  58   @param [in] Controller           Handle of device to test.
  59   @param [in] pRemainingDevicePath Not used.
  60
  61   @retval EFI_SUCCESS          This driver supports this device.
  62   @retval other                This driver does not support this device.
  63
  64 **/
  65 EFI_STATUS
  66 EFIAPI
  67 DriverSupported (
  68   IN EFI_DRIVER_BINDING_PROTOCOL * pThis,
  69   IN EFI_HANDLE Controller,
  70   IN EFI_DEVICE_PATH_PROTOCOL * pRemainingDevicePath
  71   )
  72 {
  73   CONST ESL_SOCKET_BINDING * pEnd;
  74   VOID * pInterface;
  75   CONST ESL_SOCKET_BINDING * pSocketBinding;
  76   EFI_STATUS Status;
  77
  78   //
  79   //  Assume the list is empty
  80   //
  81   Status = EFI_UNSUPPORTED;
  82
  83   //
  84   //  Walk the list of network connection points
  85   //
  86   pSocketBinding = &cEslSocketBinding[0];
  87   pEnd = &pSocketBinding[ cEslSocketBindingEntries ];
  88   while ( pEnd > pSocketBinding ) {
  89     //
  90     //  Determine if the controller supports the network protocol
  91     //
  92     Status = gBS->OpenProtocol (
  93                     Controller,
  94                     pSocketBinding->pNetworkBinding,
  95                     &pInterface,
  96                     pThis->DriverBindingHandle,
  97                     Controller,
  98                     EFI_OPEN_PROTOCOL_GET_PROTOCOL
  99                     );
 100     if ( !EFI_ERROR ( Status )) {
 101       //
 102       //  Determine if the driver is already connected
 103       //
 104       Status = gBS->OpenProtocol (
 105                       Controller,
 106                       (EFI_GUID *)pSocketBinding->pTagGuid,
 107                       &pInterface,
 108                       pThis->DriverBindingHandle,
 109                       Controller,
 110                       EFI_OPEN_PROTOCOL_GET_PROTOCOL
 111                       );
 112       if ( !EFI_ERROR ( Status )) {
 113         Status = EFI_ALREADY_STARTED;
 114       }
 115       else {
 116         if ( EFI_UNSUPPORTED == Status ) {
 117           //
 118           //  Connect the driver since the tag is not present
 119           //
 120           Status = EFI_SUCCESS;
 121         }
 122       }
 123     }
 124
 125     //
 126     //  Set the next network protocol
 127     //
 128     pSocketBinding += 1;
 129   }
 130
 131   //
 132   //  Return the device supported status
 133   //
 134   return Status;
 135 }
 136
 137
 138 /**
 139   Connect to a network adapter
 140
 141   This routine calls ::EslServiceConnect to connect the socket
 142   layer to the network adapters.  See the \ref NetworkAdapterManagement
 143   section.
 144
 145   This routine is called by the UEFI driver framework during connect
 146   processing if the controller passes the tests in ::DriverSupported.
 147
 148   @param [in] pThis                Protocol instance pointer.
 149   @param [in] Controller           Handle of device to work with.
 150   @param [in] pRemainingDevicePath Not used, always produce all possible children.
 151
 152   @retval EFI_SUCCESS          This driver is added to Controller.
 153   @retval other                This driver does not support this device.
 154
 155 **/
 156 EFI_STATUS
 157 EFIAPI
 158 DriverStart (
 159   IN EFI_DRIVER_BINDING_PROTOCOL * pThis,
 160   IN EFI_HANDLE Controller,
 161   IN EFI_DEVICE_PATH_PROTOCOL * pRemainingDevicePath
 162   )
 163 {
 164   EFI_STATUS Status;
 165
 166   DBG_ENTER ( );
 167
 168   //
 169   //  Connect to this network adapter
 170   //
 171   Status = EslServiceConnect ( pThis->DriverBindingHandle,
 172                                Controller );
 173
 174   //
 175   //  Display the driver start status
 176   //
 177   DBG_EXIT_STATUS ( Status );
 178   return Status;
 179 }
 180
 181
 182 /**
 183   Disconnect from a network adapter
 184
 185   This routine calls ::EslServiceDisconnect to disconnect the socket
 186   layer from the network adapters.  See the \ref NetworkAdapterManagement
 187   section.
 188
 189   This routine is called by ::DriverUnload when the socket layer
 190   is being unloaded.  This routine should also called by the UEFI
 191   driver framework when a network adapter is being unloaded from
 192   the system.
 193
 194   @param [in] pThis                Protocol instance pointer.
 195   @param [in] Controller           Handle of device to stop driver on.
 196   @param [in] NumberOfChildren     How many children need to be stopped.
 197   @param [in] pChildHandleBuffer   Not used.
 198
 199   @retval EFI_SUCCESS          This driver is removed Controller.
 200   @retval EFI_DEVICE_ERROR     The device could not be stopped due to a device error.
 201   @retval other                This driver was not removed from this device.
 202
 203 **/
 204 EFI_STATUS
 205 EFIAPI
 206 DriverStop (
 207   IN  EFI_DRIVER_BINDING_PROTOCOL * pThis,
 208   IN  EFI_HANDLE Controller,
 209   IN  UINTN NumberOfChildren,
 210   IN  EFI_HANDLE * pChildHandleBuffer
 211   )
 212 {
 213   EFI_STATUS Status;
 214
 215   DBG_ENTER ( );
 216
 217   //
 218   //  Disconnect the network adapters
 219   //
 220   Status = EslServiceDisconnect ( pThis->DriverBindingHandle,
 221                                   Controller );
 222
 223   //
 224   //  Display the driver start status
 225   //
 226   DBG_EXIT_STATUS ( Status );
 227   return Status;
 228 }
 229
 230
 231 /**
 232   Driver binding protocol for the SocketDxe driver.
 233 **/
 234 EFI_DRIVER_BINDING_PROTOCOL  mDriverBinding = {
 235   DriverSupported,
 236   DriverStart,
 237   DriverStop,
 238   0xa,
 239   NULL,
 240   NULL
 241 };