MdeModulePkg: Add DriverHealthManagerDxe driver.

[mirror_edk2.git] / StdLib / SocketDxe / DriverBinding.c

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