Update the Doxygen comments for the SocketDxe driver.

Change the prefix on module globals from "g" to "m" to match the coding standard.

Signed-off by: Lee Leahy

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/branches/EADK@12318 6f19259b-4bc3-4df7-8a09-765794883524

4 files changed, 71 insertions, 28 deletions

diff --git a/StdLib/SocketDxe/ComponentName.c b/StdLib/SocketDxe/ComponentName.c
index 7fe9c71..ff1f101 100644
--- a/StdLib/SocketDxe/ComponentName.c
+++ b/StdLib/SocketDxe/ComponentName.c
@@ -17,7 +17,7 @@
 /**

   EFI Component Name Protocol declaration

 **/

-GLOBAL_REMOVE_IF_UNREFERENCED EFI_COMPONENT_NAME_PROTOCOL  gComponentName = {

+GLOBAL_REMOVE_IF_UNREFERENCED EFI_COMPONENT_NAME_PROTOCOL  mComponentName = {

   GetDriverName,

   GetControllerName,

   "eng"

@@ -26,7 +26,7 @@ GLOBAL_REMOVE_IF_UNREFERENCED EFI_COMPONENT_NAME_PROTOCOL  gComponentName = {
 /**

   EFI Component Name 2 Protocol declaration

 **/

-GLOBAL_REMOVE_IF_UNREFERENCED EFI_COMPONENT_NAME2_PROTOCOL gComponentName2 = {

+GLOBAL_REMOVE_IF_UNREFERENCED EFI_COMPONENT_NAME2_PROTOCOL mComponentName2 = {

   (EFI_COMPONENT_NAME2_GET_DRIVER_NAME) GetDriverName,

   (EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME) GetControllerName,

   "en"

@@ -91,7 +91,7 @@ GetDriverName (
              pThis->SupportedLanguages,

              mDriverNameTable,

              ppDriverName,

-             (BOOLEAN)(pThis == &gComponentName)

+             (BOOLEAN)(pThis == &mComponentName)

              );

   return Status;

 }

diff --git a/StdLib/SocketDxe/DriverBinding.c b/StdLib/SocketDxe/DriverBinding.c
index b3ab58f..4d68f37 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.

@@ -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,

diff --git a/StdLib/SocketDxe/EntryUnload.c b/StdLib/SocketDxe/EntryUnload.c
index 8750cc9..1f550c9 100644
--- a/StdLib/SocketDxe/EntryUnload.c
+++ b/StdLib/SocketDxe/EntryUnload.c
@@ -115,7 +115,7 @@ DriverUnload (
       //

       Max = BufferSize / sizeof ( pHandle[ 0 ]);

       for ( Index = 0; Max > Index; Index++ ) {

-        Status = DriverStop ( &gDriverBinding,

+        Status = DriverStop ( &mDriverBinding,

                               pHandle[ Index ],

                               0,

                               NULL );

@@ -156,11 +156,11 @@ DriverUnload (
       Status = gBS->UninstallMultipleProtocolInterfaces (

                   ImageHandle,

                   &gEfiDriverBindingProtocolGuid,

-                  &gDriverBinding,

+                  &mDriverBinding,

                   &gEfiComponentNameProtocolGuid,

-                  &gComponentName,

+                  &mComponentName,

                   &gEfiComponentName2ProtocolGuid,

-                  &gComponentName2,

+                  &mComponentName2,

                   NULL

                   );

       if ( !EFI_ERROR ( Status )) {

@@ -242,10 +242,10 @@ EntryPoint (
     Status = EfiLibInstallDriverBindingComponentName2 (

                ImageHandle,

                pSystemTable,

-               &gDriverBinding,

+               &mDriverBinding,

                ImageHandle,

-               &gComponentName,

-               &gComponentName2

+               &mComponentName,

+               &mComponentName2

                );

     if ( !EFI_ERROR ( Status )) {

       DEBUG (( DEBUG_POOL | DEBUG_INIT | DEBUG_INFO,

@@ -280,11 +280,11 @@ EntryPoint (
         gBS->UninstallMultipleProtocolInterfaces (

                 ImageHandle,

                 &gEfiDriverBindingProtocolGuid,

-                &gDriverBinding,

+                &mDriverBinding,

                 &gEfiComponentNameProtocolGuid,

-                &gComponentName,

+                &mComponentName,

                 &gEfiComponentName2ProtocolGuid,

-                &gComponentName2,

+                &mComponentName2,

                 NULL

                 );

         DEBUG (( DEBUG_POOL | DEBUG_INIT | DEBUG_INFO,

diff --git a/StdLib/SocketDxe/Socket.h b/StdLib/SocketDxe/Socket.h
index dfa4dad..7d8334c 100644
--- a/StdLib/SocketDxe/Socket.h
+++ b/StdLib/SocketDxe/Socket.h
@@ -23,9 +23,9 @@
 // Protocol Declarations

 //------------------------------------------------------------------------------

 

-extern EFI_COMPONENT_NAME_PROTOCOL gComponentName;    ///<  Component name protocol declaration

-extern EFI_COMPONENT_NAME2_PROTOCOL gComponentName2;  ///<  Component name 2 protocol declaration

-extern EFI_DRIVER_BINDING_PROTOCOL gDriverBinding;    ///<  Driver binding protocol declaration

+extern EFI_COMPONENT_NAME_PROTOCOL mComponentName;    ///<  Component name protocol declaration

+extern EFI_COMPONENT_NAME2_PROTOCOL mComponentName2;  ///<  Component name 2 protocol declaration

+extern EFI_DRIVER_BINDING_PROTOCOL mDriverBinding;    ///<  Driver binding protocol declaration

 extern EFI_SERVICE_BINDING_PROTOCOL mServiceBinding;  ///<  Service binding protocol delcaration

 

 //------------------------------------------------------------------------------