X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=StdLib%2FSocketDxe%2FDriverBinding.c;h=4d68f37be2674d927417fd62edd8b12990024f90;hb=8aab575c26e94c65b8cb3a44dc944c3c47ee1c07;hp=7de7f62a354d424eb463cc3800af7c699c44c89b;hpb=d7ce700605e1af0e455e31ec11f19ff21d26b525;p=mirror_edk2.git

diff --git a/StdLib/SocketDxe/DriverBinding.c b/StdLib/SocketDxe/DriverBinding.c
index 7de7f62a35..4d68f37be2 100644
--- a/StdLib/SocketDxe/DriverBinding.c
+++ b/StdLib/SocketDxe/DriverBinding.c
@@ -10,6 +10,31 @@
   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
+
+  \section NetworkAdapterManagement Network Adapter Management
+  Network adapters may come and go over the life if a system running
+  UEFI.  The SocketDxe driver uses the driver binding API to manage
+  the connections to network adapters.
+
+  The ::DriverSupported routine selects network adapters that the
+  socket layer is not using.  This determination by the lack of the
+  tag GUID associated with the network protocol in the
+  ::cEslSocketBinding array.  The selected network adapters are 
+  passed to the ::DriverStart routine.
+
+  The ::DriverStart routine calls the ::EslServiceConnect routine
+  to create an ::ESL_SERVICE structure to manage the network adapter
+  for the socket layer.  EslServiceConnect also installs the tag
+  GUID on the network adapter to prevent future calls from
+  ::DriverSupported.  EslService also calls the network specific
+  initialization routine listed in ESL_SOCKET_BINDING::pfnInitialize
+  field of the ::cEslSocketBinding entry.
+
+  The ::DriverStop routine calls the ::EslServiceDisconnect routine
+  to undo the work done by ::DriverStart.  The socket layer must break
+  the active network connections, then remove the tag GUIDs from the
+  controller handle and free ::ESL_SERVICE structure.
+
 **/
 
 #include "Socket.h"
@@ -17,10 +42,17 @@
 /**
   Verify the controller type
 
-  Determine if any of the network service binding protocols exist on
-  the controller handle.  If so, verify that these protocols are not
-  already in use.  Call ::DriverStart for any network service binding
-  protocol that is not in use.
+  This routine walks the cEslSocketBinding array to determines if
+  the controller is a network adapter by supporting any of the
+  network protocols required by the sockets layer.  If so, the
+  routine verifies that the socket layer is not already using the
+  support by looking for the tag GUID listed in the corresponding
+  array entry.  The controller handle is passed to the ::DriverStart
+  routine if sockets can use the network adapter.
+  See the \ref NetworkAdapterManagement section.
+
+  This routine is called by the UEFI driver framework during connect
+  processing.
 
   @param [in] pThis                Protocol instance pointer.
   @param [in] Controller           Handle of device to test.
@@ -38,9 +70,9 @@ DriverSupported (
   IN EFI_DEVICE_PATH_PROTOCOL * pRemainingDevicePath
   )
 {
-  CONST DT_SOCKET_BINDING * pEnd;
+  CONST ESL_SOCKET_BINDING * pEnd;
   VOID * pInterface;
-  CONST DT_SOCKET_BINDING * pSocketBinding;
+  CONST ESL_SOCKET_BINDING * pSocketBinding;
   EFI_STATUS Status;
 
   //
@@ -104,11 +136,14 @@ DriverSupported (
 
 
 /**
-  Connect to the network service bindings
+  Connect to a network adapter
 
-  Walk the network service protocols on the controller handle and
-  locate any that are not in use.  Create service structures to
-  manage the service binding for the socket driver.
+  This routine calls ::EslServiceConnect to connect the socket
+  layer to the network adapters.  See the \ref NetworkAdapterManagement
+  section.
+
+  This routine is called by the UEFI driver framework during connect
+  processing if the controller passes the tests in ::DriverSupported.
 
   @param [in] pThis                Protocol instance pointer.
   @param [in] Controller           Handle of device to work with.
@@ -145,9 +180,17 @@ DriverStart (
 
 
 /**
-  Stop this driver on Controller by removing NetworkInterfaceIdentifier protocol and
-  closing the DevicePath and PciIo protocols on Controller.
+  Disconnect from a network adapter
+
+  This routine calls ::EslServiceDisconnect to disconnect the socket
+  layer from the network adapters.  See the \ref NetworkAdapterManagement
+  section.
 
+  This routine is called by ::DriverUnload when the socket layer
+  is being unloaded.  This routine should also called by the UEFI
+  driver framework when a network adapter is being unloaded from
+  the system.
+  
   @param [in] pThis                Protocol instance pointer.
   @param [in] Controller           Handle of device to stop driver on.
   @param [in] NumberOfChildren     How many children need to be stopped.
@@ -186,9 +229,9 @@ DriverStop (
 
 
 /**
-  Driver binding protocol definition
+  Driver binding protocol for the SocketDxe driver.
 **/
-EFI_DRIVER_BINDING_PROTOCOL  gDriverBinding = {
+EFI_DRIVER_BINDING_PROTOCOL  mDriverBinding = {
   DriverSupported,
   DriverStart,
   DriverStop,