fix code style issue and add function header
authorniry <niry@6f19259b-4bc3-4df7-8a09-765794883524>
Tue, 18 Nov 2008 04:52:51 +0000 (04:52 +0000)
committerniry <niry@6f19259b-4bc3-4df7-8a09-765794883524>
Tue, 18 Nov 2008 04:52:51 +0000 (04:52 +0000)
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6570 6f19259b-4bc3-4df7-8a09-765794883524

MdeModulePkg/Universal/Network/MnpDxe/MnpConfig.c
MdeModulePkg/Universal/Network/MnpDxe/MnpDriver.c
MdeModulePkg/Universal/Network/MnpDxe/MnpDriver.h
MdeModulePkg/Universal/Network/MnpDxe/MnpImpl.h
MdeModulePkg/Universal/Network/MnpDxe/MnpIo.c
MdeModulePkg/Universal/Network/MnpDxe/MnpMain.c

index fd03ed5..e29f097 100644 (file)
@@ -52,54 +52,162 @@ EFI_MANAGED_NETWORK_CONFIG_DATA mMnpDefaultConfigData = {
   FALSE\r
 };\r
 \r
-EFI_STATUS\r
-MnpAddFreeNbuf (\r
-  IN MNP_SERVICE_DATA  *MnpServiceData,\r
-  IN UINTN             Count\r
-  );\r
-\r
-EFI_STATUS\r
-MnpStartSnp (\r
-  IN EFI_SIMPLE_NETWORK_PROTOCOL  *Snp\r
-  );\r
-\r
-EFI_STATUS\r
-MnpStopSnp (\r
-  IN EFI_SIMPLE_NETWORK_PROTOCOL  *Snp\r
-  );\r
+/**\r
+  Configure the Snp receive filters according to the instances' receive filter\r
+  settings.\r
 \r
-EFI_STATUS\r
-MnpStart (\r
-  IN MNP_SERVICE_DATA  *MnpServiceData,\r
-  IN BOOLEAN           IsConfigUpdate,\r
-  IN BOOLEAN           EnableSystemPoll\r
-  );\r
+  @param  MnpServiceData        Pointer to the mnp service context data.\r
 \r
-EFI_STATUS\r
-MnpStop (\r
-  IN MNP_SERVICE_DATA  *MnpServiceData\r
-  );\r
+  @retval EFI_SUCCESS           The receive filters is configured.\r
+  @retval EFI_OUT_OF_RESOURCES  The receive filters can't be configured due to lack\r
+                                of memory resource.\r
 \r
+**/\r
 EFI_STATUS\r
 MnpConfigReceiveFilters (\r
   IN MNP_SERVICE_DATA  *MnpServiceData\r
-  );\r
+  )\r
+{\r
+  EFI_STATUS                  Status;\r
+  EFI_SIMPLE_NETWORK_PROTOCOL *Snp;\r
+  EFI_MAC_ADDRESS             *MCastFilter;\r
+  UINT32                      MCastFilterCnt;\r
+  UINT32                      EnableFilterBits;\r
+  UINT32                      DisableFilterBits;\r
+  BOOLEAN                     ResetMCastFilters;\r
+  LIST_ENTRY                  *Entry;\r
+  UINT32                      Index;\r
+  MNP_GROUP_ADDRESS           *GroupAddress;\r
 \r
-EFI_STATUS\r
-MnpGroupOpAddCtrlBlk (\r
-  IN MNP_INSTANCE_DATA        *Instance,\r
-  IN MNP_GROUP_CONTROL_BLOCK  *CtrlBlk,\r
-  IN MNP_GROUP_ADDRESS        *GroupAddress OPTIONAL,\r
-  IN EFI_MAC_ADDRESS          *MacAddress,\r
-  IN UINT32                   HwAddressSize\r
-  );\r
+  NET_CHECK_SIGNATURE (MnpServiceData, MNP_SERVICE_DATA_SIGNATURE);\r
 \r
-BOOLEAN\r
-MnpGroupOpDelCtrlBlk (\r
-  IN MNP_INSTANCE_DATA        *Instance,\r
-  IN MNP_GROUP_CONTROL_BLOCK  *CtrlBlk\r
+  Snp = MnpServiceData->Snp;\r
+\r
+  //\r
+  // Initialize the enable filter and disable filter.\r
+  //\r
+  EnableFilterBits  = 0;\r
+  DisableFilterBits = Snp->Mode->ReceiveFilterMask;\r
+\r
+  if (MnpServiceData->UnicastCount != 0) {\r
+    //\r
+    // Enable unicast if any instance wants to receive unicast.\r
+    //\r
+    EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_UNICAST;\r
+  }\r
+\r
+  if (MnpServiceData->BroadcastCount != 0) {\r
+    //\r
+    // Enable broadcast if any instance wants to receive broadcast.\r
+    //\r
+    EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST;\r
+  }\r
+\r
+  MCastFilter       = NULL;\r
+  MCastFilterCnt    = 0;\r
+  ResetMCastFilters = TRUE;\r
+\r
+  if ((MnpServiceData->MulticastCount != 0) && (MnpServiceData->GroupAddressCount != 0)) {\r
+    //\r
+    // There are instances configured to receive multicast and already some group\r
+    // addresses are joined.\r
+    //\r
+\r
+    ResetMCastFilters = FALSE;\r
+\r
+    if (MnpServiceData->GroupAddressCount <= Snp->Mode->MaxMCastFilterCount) {\r
+      //\r
+      // The joind group address is less than simple network's maximum count.\r
+      // Just configure the snp to do the multicast filtering.\r
+      //\r
+\r
+      EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST;\r
+\r
+      //\r
+      // Allocate pool for the mulicast addresses.\r
+      //\r
+      MCastFilterCnt  = MnpServiceData->GroupAddressCount;\r
+      MCastFilter     = AllocatePool (sizeof (EFI_MAC_ADDRESS) * MCastFilterCnt);\r
+      if (MCastFilter == NULL) {\r
+\r
+        DEBUG ((EFI_D_ERROR, "MnpConfigReceiveFilters: Failed to allocate memory resource for MCastFilter.\n"));\r
+        return EFI_OUT_OF_RESOURCES;\r
+      }\r
+\r
+      //\r
+      // Fill the multicast HW address buffer.\r
+      //\r
+      Index = 0;\r
+      NET_LIST_FOR_EACH (Entry, &MnpServiceData->GroupAddressList) {\r
+\r
+        GroupAddress            = NET_LIST_USER_STRUCT (Entry, MNP_GROUP_ADDRESS, AddrEntry);\r
+        CopyMem (MCastFilter + Index, &GroupAddress->Address, sizeof (*(MCastFilter + Index)));\r
+        Index++;\r
+\r
+        ASSERT (Index <= MCastFilterCnt);\r
+      }\r
+    } else {\r
+      //\r
+      // The maximum multicast is reached, set the filter to be promiscuous\r
+      // multicast.\r
+      //\r
+\r
+      if (Snp->Mode->ReceiveFilterMask & EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST) {\r
+        EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST;\r
+      } else {\r
+        //\r
+        // Either MULTICAST or PROMISCUOUS_MULTICAST is not supported by Snp,\r
+        // set the NIC to be promiscuous although this will tremendously degrade\r
+        // the performance.\r
+        //\r
+        EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS;\r
+      }\r
+    }\r
+  }\r
+\r
+  if (MnpServiceData->PromiscuousCount != 0) {\r
+    //\r
+    // Enable promiscuous if any instance wants to receive promiscuous.\r
+    //\r
+    EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS;\r
+  }\r
+\r
+  //\r
+  // Set the disable filter.\r
+  //\r
+  DisableFilterBits ^= EnableFilterBits;\r
+\r
+  //\r
+  // Configure the receive filters of SNP.\r
+  //\r
+  Status = Snp->ReceiveFilters (\r
+                  Snp,\r
+                  EnableFilterBits,\r
+                  DisableFilterBits,\r
+                  ResetMCastFilters,\r
+                  MCastFilterCnt,\r
+                  MCastFilter\r
+                  );\r
+  DEBUG_CODE (\r
+    if (EFI_ERROR (Status)) {\r
+\r
+    DEBUG (\r
+      (EFI_D_ERROR,\r
+      "MnpConfigReceiveFilters: Snp->ReceiveFilters failed, %r.\n",\r
+      Status)\r
+      );\r
+  }\r
   );\r
 \r
+  if (MCastFilter != NULL) {\r
+    //\r
+    // Free the buffer used to hold the group addresses.\r
+    //\r
+    gBS->FreePool (MCastFilter);\r
+  }\r
+\r
+  return Status;\r
+}\r
 \r
 /**\r
   Add some NET_BUF into MnpServiceData->FreeNbufQue. The buffer length of\r
@@ -235,8 +343,6 @@ ON_EXIT:
   @param  MnpServiceData        Pointer to the mnp service context data.\r
   @param  Nbuf                  Pointer to the NET_BUF to free.\r
 \r
-  @return None.\r
-\r
 **/\r
 VOID\r
 MnpFreeNbuf (\r
@@ -269,7 +375,8 @@ MnpFreeNbuf (
   Initialize the mnp service context data.\r
 \r
   @param  MnpServiceData        Pointer to the mnp service context data.\r
-  @param  Snp                   Pointer to the simple network protocol.\r
+  @param  ImageHandle           The driver image handle.\r
+  @param  ControllerHandle      Handle of device to bind driver to.\r
 \r
   @retval EFI_SUCCESS           The mnp service context is initialized.\r
   @retval Other                 Some error occurs.\r
@@ -454,8 +561,7 @@ ERROR:
   Flush the mnp service context data.\r
 \r
   @param  MnpServiceData        Pointer to the mnp service context data.\r
-\r
-  @return None.\r
+  @param  ImageHandle           The driver image handle.\r
 \r
 **/\r
 VOID\r
@@ -521,8 +627,6 @@ MnpFlushServiceData (
   @param  Instance              Pointer to the mnp instance context data to\r
                                 initialize.\r
 \r
-  @return None.\r
-\r
 **/\r
 VOID\r
 MnpInitializeInstanceData (\r
@@ -605,7 +709,6 @@ MnpTokenExist (
   return EFI_SUCCESS;\r
 }\r
 \r
-\r
 /**\r
   Cancel the token specified by Arg if it matches the token in Item.\r
 \r
@@ -890,8 +993,6 @@ MnpStop (
 \r
   @param  Instance              Pointer to the mnp instance context data.\r
 \r
-  @return None.\r
-\r
 **/\r
 VOID\r
 MnpFlushRcvdDataQueue (\r
@@ -1063,163 +1164,6 @@ MnpConfigureInstance (
 }\r
 \r
 \r
-/**\r
-  Configure the Snp receive filters according to the instances' receive filter\r
-  settings.\r
-\r
-  @param  MnpServiceData        Pointer to the mnp service context data.\r
-\r
-  @retval EFI_SUCCESS           The receive filters is configured.\r
-  @retval EFI_OUT_OF_RESOURCES  The receive filters can't be configured due to lack\r
-                                of memory resource.\r
-\r
-**/\r
-EFI_STATUS\r
-MnpConfigReceiveFilters (\r
-  IN MNP_SERVICE_DATA  *MnpServiceData\r
-  )\r
-{\r
-  EFI_STATUS                  Status;\r
-  EFI_SIMPLE_NETWORK_PROTOCOL *Snp;\r
-  EFI_MAC_ADDRESS             *MCastFilter;\r
-  UINT32                      MCastFilterCnt;\r
-  UINT32                      EnableFilterBits;\r
-  UINT32                      DisableFilterBits;\r
-  BOOLEAN                     ResetMCastFilters;\r
-  LIST_ENTRY                  *Entry;\r
-  UINT32                      Index;\r
-  MNP_GROUP_ADDRESS           *GroupAddress;\r
-\r
-  NET_CHECK_SIGNATURE (MnpServiceData, MNP_SERVICE_DATA_SIGNATURE);\r
-\r
-  Snp = MnpServiceData->Snp;\r
-\r
-  //\r
-  // Initialize the enable filter and disable filter.\r
-  //\r
-  EnableFilterBits  = 0;\r
-  DisableFilterBits = Snp->Mode->ReceiveFilterMask;\r
-\r
-  if (MnpServiceData->UnicastCount != 0) {\r
-    //\r
-    // Enable unicast if any instance wants to receive unicast.\r
-    //\r
-    EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_UNICAST;\r
-  }\r
-\r
-  if (MnpServiceData->BroadcastCount != 0) {\r
-    //\r
-    // Enable broadcast if any instance wants to receive broadcast.\r
-    //\r
-    EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_BROADCAST;\r
-  }\r
-\r
-  MCastFilter       = NULL;\r
-  MCastFilterCnt    = 0;\r
-  ResetMCastFilters = TRUE;\r
-\r
-  if ((MnpServiceData->MulticastCount != 0) && (MnpServiceData->GroupAddressCount != 0)) {\r
-    //\r
-    // There are instances configured to receive multicast and already some group\r
-    // addresses are joined.\r
-    //\r
-\r
-    ResetMCastFilters = FALSE;\r
-\r
-    if (MnpServiceData->GroupAddressCount <= Snp->Mode->MaxMCastFilterCount) {\r
-      //\r
-      // The joind group address is less than simple network's maximum count.\r
-      // Just configure the snp to do the multicast filtering.\r
-      //\r
-\r
-      EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST;\r
-\r
-      //\r
-      // Allocate pool for the mulicast addresses.\r
-      //\r
-      MCastFilterCnt  = MnpServiceData->GroupAddressCount;\r
-      MCastFilter     = AllocatePool (sizeof (EFI_MAC_ADDRESS) * MCastFilterCnt);\r
-      if (MCastFilter == NULL) {\r
-\r
-        DEBUG ((EFI_D_ERROR, "MnpConfigReceiveFilters: Failed to allocate memory resource for MCastFilter.\n"));\r
-        return EFI_OUT_OF_RESOURCES;\r
-      }\r
-\r
-      //\r
-      // Fill the multicast HW address buffer.\r
-      //\r
-      Index = 0;\r
-      NET_LIST_FOR_EACH (Entry, &MnpServiceData->GroupAddressList) {\r
-\r
-        GroupAddress            = NET_LIST_USER_STRUCT (Entry, MNP_GROUP_ADDRESS, AddrEntry);\r
-        CopyMem (MCastFilter + Index, &GroupAddress->Address, sizeof (*(MCastFilter + Index)));\r
-        Index++;\r
-\r
-        ASSERT (Index <= MCastFilterCnt);\r
-      }\r
-    } else {\r
-      //\r
-      // The maximum multicast is reached, set the filter to be promiscuous\r
-      // multicast.\r
-      //\r
-\r
-      if (Snp->Mode->ReceiveFilterMask & EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST) {\r
-        EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS_MULTICAST;\r
-      } else {\r
-        //\r
-        // Either MULTICAST or PROMISCUOUS_MULTICAST is not supported by Snp,\r
-        // set the NIC to be promiscuous although this will tremendously degrade\r
-        // the performance.\r
-        //\r
-        EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS;\r
-      }\r
-    }\r
-  }\r
-\r
-  if (MnpServiceData->PromiscuousCount != 0) {\r
-    //\r
-    // Enable promiscuous if any instance wants to receive promiscuous.\r
-    //\r
-    EnableFilterBits |= EFI_SIMPLE_NETWORK_RECEIVE_PROMISCUOUS;\r
-  }\r
-\r
-  //\r
-  // Set the disable filter.\r
-  //\r
-  DisableFilterBits ^= EnableFilterBits;\r
-\r
-  //\r
-  // Configure the receive filters of SNP.\r
-  //\r
-  Status = Snp->ReceiveFilters (\r
-                  Snp,\r
-                  EnableFilterBits,\r
-                  DisableFilterBits,\r
-                  ResetMCastFilters,\r
-                  MCastFilterCnt,\r
-                  MCastFilter\r
-                  );\r
-  DEBUG_CODE (\r
-    if (EFI_ERROR (Status)) {\r
-\r
-    DEBUG (\r
-      (EFI_D_ERROR,\r
-      "MnpConfigReceiveFilters: Snp->ReceiveFilters failed, %r.\n",\r
-      Status)\r
-      );\r
-  }\r
-  );\r
-\r
-  if (MCastFilter != NULL) {\r
-    //\r
-    // Free the buffer used to hold the group addresses.\r
-    //\r
-    gBS->FreePool (MCastFilter);\r
-  }\r
-\r
-  return Status;\r
-}\r
-\r
 \r
 /**\r
   Add a group address control block which controls the MacAddress for\r
index dd1fcd8..b6c0138 100644 (file)
@@ -31,18 +31,22 @@ EFI_DRIVER_BINDING_PROTOCOL gMnpDriverBinding = {
   NULL\r
 };\r
 \r
-\r
 /**\r
-  Test to see if this driver supports ControllerHandle.\r
-\r
-  @param  This                   Protocol instance pointer.\r
-  @param  ControllerHandle       Handle of device to test.\r
-  @param  RemainingDevicePath    Optional parameter use to pick a specific child\r
-                                 device to start.\r
-\r
-  @retval EFI_SUCCES             This driver supports this device.\r
-  @retval EFI_ALREADY_STARTED    This driver is already running on this device.\r
-  @retval other                  This driver does not support this device.\r
+  Test to see if this driver supports ControllerHandle. This service\r
+  is called by the EFI boot service ConnectController(). In\r
+  order to make drivers as small as possible, there are a few calling\r
+  restrictions for this service. ConnectController() must\r
+  follow these calling restrictions. If any other agent wishes to call\r
+  Supported() it must also follow these calling restrictions.\r
+\r
+  @param  This                Protocol instance pointer.\r
+  @param  ControllerHandle    Handle of device to test\r
+  @param  RemainingDevicePath Optional parameter use to pick a specific child\r
+                              device to start.\r
+\r
+  @retval EFI_SUCCESS         This driver supports this device\r
+  @retval EFI_ALREADY_STARTED This driver is already running on this device\r
+  @retval other               This driver does not support this device\r
 \r
 **/\r
 EFI_STATUS\r
@@ -102,17 +106,21 @@ MnpDriverBindingSupported (
 \r
 \r
 /**\r
-  Start this driver on ControllerHandle.\r
-\r
-  @param  This                   Protocol instance pointer.\r
-  @param  ControllerHandle       Handle of device to bind driver to.\r
-  @param  RemainingDevicePath    Optional parameter use to pick a specific child\r
-                                 device to start.\r
-\r
-  @retval EFI_SUCCES             This driver is added to ControllerHandle.\r
-  @retval EFI_ALREADY_STARTED    This driver is already running on\r
-                                 ControllerHandle.\r
-  @retval other                  This driver does not support this device.\r
+  Start this driver on ControllerHandle. This service is called by the\r
+  EFI boot service ConnectController(). In order to make\r
+  drivers as small as possible, there are a few calling restrictions for\r
+  this service. ConnectController() must follow these\r
+  calling restrictions. If any other agent wishes to call Start() it\r
+  must also follow these calling restrictions.\r
+\r
+  @param  This                 Protocol instance pointer.\r
+  @param  ControllerHandle     Handle of device to bind driver to.\r
+  @param  RemainingDevicePath  Optional parameter use to pick a specific child\r
+                               device to start.\r
+\r
+  @retval EFI_SUCCESS          This driver is added to ControllerHandle\r
+  @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle\r
+  @retval other                This driver does not support this device\r
 \r
 **/\r
 EFI_STATUS\r
@@ -175,18 +183,22 @@ ErrorExit:
   return Status;\r
 }\r
 \r
-\r
 /**\r
-  Stop this driver on ControllerHandle.\r
-\r
-  @param  This                   Protocol instance pointer.\r
-  @param  ControllerHandle       Handle of device to stop driver on.\r
-  @param  NumberOfChildren       Number of Handles in ChildHandleBuffer. If number\r
-                                 of children is zero stop the entire bus driver.\r
-  @param  ChildHandleBuffer      List of Child Handles to Stop.\r
-\r
-  @retval EFI_SUCCES             This driver is removed ControllerHandle.\r
-  @retval other                  This driver was not removed from this device.\r
+  Stop this driver on ControllerHandle. This service is called by the\r
+  EFI boot service DisconnectController(). In order to\r
+  make drivers as small as possible, there are a few calling\r
+  restrictions for this service. DisconnectController()\r
+  must follow these calling restrictions. If any other agent wishes\r
+  to call Stop() it must also follow these calling restrictions.\r
+  \r
+  @param  This              Protocol instance pointer.\r
+  @param  ControllerHandle  Handle of device to stop driver on\r
+  @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of\r
+                            children is zero stop the entire bus driver.\r
+  @param  ChildHandleBuffer List of Child Handles to Stop.\r
+\r
+  @retval EFI_SUCCESS       This driver is removed ControllerHandle\r
+  @retval other             This driver was not removed from this device\r
 \r
 **/\r
 EFI_STATUS\r
@@ -505,31 +517,24 @@ MnpServiceBindingDestroyChild (
   return Status;\r
 }\r
 \r
+/**\r
+  The entry point for Mnp driver which installs the driver binding and component\r
+  name protocol on its ImageHandle.\r
+\r
+  @param  ImageHandle   The image handle of the driver.\r
+  @param  SystemTable   The system table.\r
+\r
+  @retval EFI_SUCCES       the driver binding and component name protocols are \r
+                           successfully installed.\r
+  @retval other            failed.\r
 \r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpDriverEntryPoint (\r
   IN EFI_HANDLE        ImageHandle,\r
   IN EFI_SYSTEM_TABLE  *SystemTable\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  The entry point for Mnp driver which installs the driver binding and component name\r
-  protocol on its ImageHandle.\r
-\r
-Arguments:\r
-\r
-  ImageHandle - The image handle of the driver.\r
-  SystemTable - The system table.\r
-\r
-Returns:\r
-\r
-  EFI_SUCCESS - If the driver binding and component name protocols are successfully\r
-                installed, otherwise if failed.\r
-\r
---*/\r
 {\r
   return EfiLibInstallDriverBindingComponentName2 (\r
            ImageHandle,\r
index 050b9e0..198c914 100644 (file)
@@ -94,22 +94,77 @@ typedef struct _MNP_SERVICE_DATA {
   MNP_SERVICE_DATA_SIGNATURE \\r
   )\r
 \r
+/**\r
+  Test to see if this driver supports ControllerHandle. This service\r
+  is called by the EFI boot service ConnectController(). In\r
+  order to make drivers as small as possible, there are a few calling\r
+  restrictions for this service. ConnectController() must\r
+  follow these calling restrictions. If any other agent wishes to call\r
+  Supported() it must also follow these calling restrictions.\r
+\r
+  @param  This                Protocol instance pointer.\r
+  @param  ControllerHandle    Handle of device to test\r
+  @param  RemainingDevicePath Optional parameter use to pick a specific child\r
+                              device to start.\r
+\r
+  @retval EFI_SUCCESS         This driver supports this device\r
+  @retval EFI_ALREADY_STARTED This driver is already running on this device\r
+  @retval other               This driver does not support this device\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpDriverBindingSupported (\r
-  IN EFI_DRIVER_BINDING_PROTOCOL  * This,\r
+  IN EFI_DRIVER_BINDING_PROTOCOL  *This,\r
   IN EFI_HANDLE                   ControllerHandle,\r
-  IN EFI_DEVICE_PATH_PROTOCOL     * RemainingDevicePath OPTIONAL\r
+  IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL\r
   );\r
 \r
+/**\r
+  Start this driver on ControllerHandle. This service is called by the\r
+  EFI boot service ConnectController(). In order to make\r
+  drivers as small as possible, there are a few calling restrictions for\r
+  this service. ConnectController() must follow these\r
+  calling restrictions. If any other agent wishes to call Start() it\r
+  must also follow these calling restrictions.\r
+\r
+  @param  This                 Protocol instance pointer.\r
+  @param  ControllerHandle     Handle of device to bind driver to.\r
+  @param  RemainingDevicePath  Optional parameter use to pick a specific child\r
+                               device to start.\r
+\r
+  @retval EFI_SUCCESS          This driver is added to ControllerHandle\r
+  @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle\r
+  @retval other                This driver does not support this device\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpDriverBindingStart (\r
-  IN EFI_DRIVER_BINDING_PROTOCOL  * This,\r
+  IN EFI_DRIVER_BINDING_PROTOCOL  *This,\r
   IN EFI_HANDLE                   ControllerHandle,\r
-  IN EFI_DEVICE_PATH_PROTOCOL     * RemainingDevicePath OPTIONAL\r
+  IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL\r
   );\r
 \r
+\r
+/**\r
+  Stop this driver on ControllerHandle. This service is called by the\r
+  EFI boot service DisconnectController(). In order to\r
+  make drivers as small as possible, there are a few calling\r
+  restrictions for this service. DisconnectController()\r
+  must follow these calling restrictions. If any other agent wishes\r
+  to call Stop() it must also follow these calling restrictions.\r
+  \r
+  @param  This              Protocol instance pointer.\r
+  @param  ControllerHandle  Handle of device to stop driver on\r
+  @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of\r
+                            children is zero stop the entire bus driver.\r
+  @param  ChildHandleBuffer List of Child Handles to Stop.\r
+\r
+  @retval EFI_SUCCESS       This driver is removed ControllerHandle\r
+  @retval other             This driver was not removed from this device\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpDriverBindingStop (\r
@@ -119,6 +174,22 @@ MnpDriverBindingStop (
   IN EFI_HANDLE                   *ChildHandleBuffer\r
   );\r
 \r
+/**\r
+  Creates a child handle with a set of I/O services.\r
+\r
+  @param  This                   Protocol instance pointer.\r
+  @param  ChildHandle            Pointer to the handle of the child to create. If\r
+                                 it is NULL, then a new handle is created. If it is\r
+                                 not NULL, then the I/O services are  added to the\r
+                                 existing child handle.\r
+\r
+  @retval EFI_SUCCES             The child handle was created with the I/O\r
+                                 services.\r
+  @retval EFI_OUT_OF_RESOURCES   There are not enough resources availabe to create\r
+                                 the child.\r
+  @retval other                  The child handle was not created.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpServiceBindingCreateChild (\r
@@ -126,6 +197,22 @@ MnpServiceBindingCreateChild (
   IN EFI_HANDLE                    *ChildHandle\r
   );\r
 \r
+/**\r
+  Destroys a child handle with a set of I/O services.\r
+\r
+  @param  This                   Protocol instance pointer.\r
+  @param  ChildHandle            Handle of the child to destroy.\r
+\r
+  @retval EFI_SUCCES             The I/O services were removed from the child\r
+                                 handle.\r
+  @retval EFI_UNSUPPORTED        The child handle does not support the I/O services\r
+                                  that are being removed.\r
+  @retval EFI_INVALID_PARAMETER  Child handle is not a valid EFI Handle.\r
+  @retval EFI_ACCESS_DENIED      The child handle could not be destroyed because\r
+                                 its  I/O services are being used.\r
+  @retval other                  The child handle was not destroyed.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpServiceBindingDestroyChild (\r
index 4b62967..417b72f 100644 (file)
@@ -96,6 +96,17 @@ typedef struct _MNP_RXDATA_WRAP {
   UINT64                            TimeoutTick;\r
 } MNP_RXDATA_WRAP;\r
 \r
+/**\r
+  Initialize the mnp service context data.\r
+\r
+  @param  MnpServiceData        Pointer to the mnp service context data.\r
+  @param  ImageHandle           The driver image handle.\r
+  @param  ControllerHandle      Handle of device to bind driver to.\r
+\r
+  @retval EFI_SUCCESS           The mnp service context is initialized.\r
+  @retval Other                 Some error occurs.\r
+\r
+**/\r
 EFI_STATUS\r
 MnpInitializeServiceData (\r
   IN MNP_SERVICE_DATA  *MnpServiceData,\r
@@ -103,18 +114,47 @@ MnpInitializeServiceData (
   IN EFI_HANDLE        ControllerHandle\r
   );\r
 \r
+/**\r
+  Flush the mnp service context data.\r
+\r
+  @param  MnpServiceData        Pointer to the mnp service context data.\r
+  @param  ImageHandle           The driver image handle.\r
+\r
+**/\r
 VOID\r
 MnpFlushServiceData (\r
   IN MNP_SERVICE_DATA  *MnpServiceData,\r
   IN EFI_HANDLE        ImageHandle\r
   );\r
 \r
+/**\r
+  Initialize the mnp instance context data.\r
+\r
+  @param  MnpServiceData        Pointer to the mnp service context data.\r
+  @param  Instance              Pointer to the mnp instance context data to\r
+                                initialize.\r
+\r
+**/\r
 VOID\r
 MnpInitializeInstanceData (\r
   IN MNP_SERVICE_DATA   *MnpServiceData,\r
   IN MNP_INSTANCE_DATA  *Instance\r
   );\r
 \r
+/**\r
+  Check whether the token specified by Arg maches the token in Item.\r
+\r
+  @param  Map                   Pointer to the NET_MAP.\r
+  @param  Item                  Pointer to the NET_MAP_ITEM\r
+  @param  Arg                   Pointer to the Arg, it's a pointer to the token to\r
+                                check.\r
+\r
+  @retval EFI_SUCCESS           The token specified by Arg is different from the\r
+                                token in Item.\r
+  @retval EFI_ACCESS_DENIED     The token specified by Arg is the same as that in\r
+                                Item.\r
+\r
+**/\r
 EFI_STATUS\r
 MnpTokenExist (\r
   IN NET_MAP       *Map,\r
@@ -122,6 +162,21 @@ MnpTokenExist (
   IN VOID          *Arg\r
   );\r
 \r
+/**\r
+  Cancel the token specified by Arg if it matches the token in Item.\r
+\r
+  @param  Map                   Pointer to the NET_MAP.\r
+  @param  Item                  Pointer to the NET_MAP_ITEM\r
+  @param  Arg                   Pointer to the Arg, it's a pointer to the token to\r
+                                cancel.\r
+\r
+  @retval EFI_SUCCESS           The Arg is NULL, and the token in Item is\r
+                                cancelled, or the Arg isn't NULL, and the token in\r
+                                Item is different from the Arg.\r
+  @retval EFI_ABORTED           The Arg isn't NULL, the token in Item mathces the\r
+                                Arg, and the token is cancelled.\r
+\r
+**/\r
 EFI_STATUS\r
 MnpCancelTokens (\r
   IN NET_MAP       *Map,\r
@@ -129,17 +184,50 @@ MnpCancelTokens (
   IN VOID          *Arg\r
   );\r
 \r
+/**\r
+  Flush the instance's received data.\r
+\r
+  @param  Instance              Pointer to the mnp instance context data.\r
+\r
+**/\r
 VOID\r
 MnpFlushRcvdDataQueue (\r
   IN MNP_INSTANCE_DATA  *Instance\r
   );\r
 \r
+/**\r
+  Configure the Instance using ConfigData.\r
+\r
+  @param  Instance              Pointer to the mnp instance context data.\r
+  @param  ConfigData            Pointer to the configuration data used to configure\r
+                                the isntance.\r
+\r
+  @retval EFI_SUCCESS           The Instance is configured.\r
+  @retval EFI_UNSUPPORTED       EnableReceiveTimestamps is on and the\r
+                                implementation doesn't support it.\r
+  @retval Other                 Some error occurs.\r
+\r
+**/\r
 EFI_STATUS\r
 MnpConfigureInstance (\r
   IN MNP_INSTANCE_DATA                *Instance,\r
   IN EFI_MANAGED_NETWORK_CONFIG_DATA  *ConfigData OPTIONAL\r
   );\r
 \r
+/**\r
+  Do the group operations for this instance.\r
+\r
+  @param  Instance              Pointer to the instance context data.\r
+  @param  JoinFlag              Set to TRUE to join a group. Set to TRUE to leave a\r
+                                group/groups.\r
+  @param  MacAddress            Pointer to the group address to join or leave.\r
+  @param  CtrlBlk               Pointer to the group control block if JoinFlag if\r
+                                FALSE.\r
+\r
+  @retval EFI_SUCCESS           The group operation finished.\r
+  @retval Other                 Some error occurs.\r
+\r
+**/\r
 EFI_STATUS\r
 MnpGroupOp (\r
   IN MNP_INSTANCE_DATA        *Instance,\r
@@ -148,12 +236,32 @@ MnpGroupOp (
   IN MNP_GROUP_CONTROL_BLOCK  *CtrlBlk OPTIONAL\r
   );\r
 \r
+/**\r
+  Validates the Mnp transmit token.\r
+\r
+  @param  Instance              Pointer to the Mnp instance context data.\r
+  @param  Token                 Pointer to the transmit token to check.\r
+\r
+  @return The Token is valid or not.\r
+\r
+**/\r
 BOOLEAN\r
 MnpIsValidTxToken (\r
   IN MNP_INSTANCE_DATA                     *Instance,\r
   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token\r
   );\r
 \r
+/**\r
+  Build the packet to transmit from the TxData passed in.\r
+\r
+  @param  MnpServiceData        Pointer to the mnp service context data.\r
+  @param  TxData                Pointer to the transmit data containing the\r
+                                information to build the packet.\r
+  @param  PktBuf                Pointer to record the address of the packet.\r
+  @param  PktLen                Pointer to a UINT32 variable used to record the\r
+                                packet's length.\r
+\r
+**/\r
 VOID\r
 MnpBuildTxPacket (\r
   IN  MNP_SERVICE_DATA                   *MnpServiceData,\r
@@ -162,6 +270,19 @@ MnpBuildTxPacket (
   OUT UINT32                             *PktLen\r
   );\r
 \r
+/**\r
+  Synchronously send out the packet.\r
+\r
+  @param  MnpServiceData        Pointer to the mnp service context data.\r
+  @param  Packet                Pointer to the pakcet buffer.\r
+  @param  Length                The length of the packet.\r
+  @param  Token                 Pointer to the token the packet generated from.\r
+\r
+  @retval EFI_SUCCESS           The packet is sent out.\r
+  @retval EFI_TIMEOUT           Time out occurs, the packet isn't sent.\r
+  @retval EFI_DEVICE_ERROR      An unexpected network error occurs.\r
+\r
+**/\r
 EFI_STATUS\r
 MnpSyncSendPacket (\r
   IN MNP_SERVICE_DATA                      *MnpServiceData,\r
@@ -170,11 +291,30 @@ MnpSyncSendPacket (
   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token\r
   );\r
 \r
+/**\r
+  Try to deliver the received packet to the instance.\r
+\r
+  @param  Instance              Pointer to the mnp instance context data.\r
+\r
+  @retval EFI_SUCCESS           The received packet is delivered, or there is no\r
+                                packet to deliver, or there is no available receive\r
+                                token.\r
+  @retval EFI_OUT_OF_RESOURCES  The deliver fails due to lack of memory resource.\r
+\r
+**/\r
 EFI_STATUS\r
 MnpInstanceDeliverPacket (\r
   IN MNP_INSTANCE_DATA  *Instance\r
   );\r
 \r
+/**\r
+  Recycle the RxData and other resources used to hold and deliver the received\r
+  packet.\r
+\r
+  @param  Event                 The event this notify function registered to.\r
+  @param  Context               Pointer to the context data registerd to the Event.\r
+\r
+**/\r
 VOID\r
 EFIAPI\r
 MnpRecycleRxData (\r
@@ -182,22 +322,58 @@ MnpRecycleRxData (
   IN VOID       *Context\r
   );\r
 \r
+/**\r
+  Try to receive a packet and deliver it.\r
+\r
+  @param  MnpServiceData        Pointer to the mnp service context data.\r
+\r
+  @retval EFI_SUCCESS           add return value to function comment\r
+  @retval EFI_NOT_STARTED       The simple network protocol is not started.\r
+  @retval EFI_NOT_READY         No packet received.\r
+  @retval EFI_DEVICE_ERROR      An unexpected error occurs.\r
+\r
+**/\r
 EFI_STATUS\r
 MnpReceivePacket (\r
   IN MNP_SERVICE_DATA  *MnpServiceData\r
   );\r
 \r
+/**\r
+  Allocate a free NET_BUF from MnpServiceData->FreeNbufQue. If there is none\r
+  in the queue, first try to allocate some and add them into the queue, then\r
+  fetch the NET_BUF from the updated FreeNbufQue.\r
+\r
+  @param  MnpServiceData        Pointer to the MNP_SERVICE_DATA.\r
+\r
+  @return Pointer to the allocated free NET_BUF structure, if NULL the operation is failed.\r
+\r
+**/\r
 NET_BUF *\r
 MnpAllocNbuf (\r
   IN MNP_SERVICE_DATA  *MnpServiceData\r
   );\r
 \r
+/**\r
+  Try to reclaim the Nbuf into the buffer pool.\r
+\r
+  @param  MnpServiceData        Pointer to the mnp service context data.\r
+  @param  Nbuf                  Pointer to the NET_BUF to free.\r
+\r
+**/\r
 VOID\r
 MnpFreeNbuf (\r
   IN MNP_SERVICE_DATA  *MnpServiceData,\r
   IN NET_BUF           *Nbuf\r
   );\r
 \r
+/**\r
+  Remove the received packets if timeout occurs.\r
+\r
+  @param  Event                 The event this notify function registered to.\r
+  @param  Context               Pointer to the context data registered to the\r
+                                event.\r
+   \r
+**/\r
 VOID\r
 EFIAPI\r
 MnpCheckPacketTimeout (\r
@@ -205,6 +381,15 @@ MnpCheckPacketTimeout (
   IN VOID       *Context\r
   );\r
 \r
+/**\r
+  Poll to receive the packets from Snp. This function is either called by upperlayer\r
+  protocols/applications or the system poll timer notify mechanism.\r
+\r
+  @param  Event                 The event this notify function registered to.\r
+  @param  Context               Pointer to the context data registered to the\r
+                                event.\r
+\r
+**/\r
 VOID\r
 EFIAPI\r
 MnpSystemPoll (\r
@@ -212,14 +397,92 @@ MnpSystemPoll (
   IN VOID       *Context\r
   );\r
 \r
+/**\r
+  Returns the operational parameters for the current MNP child driver. May also\r
+  support returning the underlying SNP driver mode data.   \r
+   \r
+  The GetModeData() function is used to read the current mode data (operational\r
+  parameters) from the MNP or the underlying SNP. \r
+\r
+  @param This          Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param MnpConfigData Pointer to storage for MNP operational parameters. Type\r
+                       EFI_MANAGED_NETWORK_CONFIG_DATA is defined in "Related\r
+                       Definitions" below.\r
+  @param SnpModeData   Pointer to storage for SNP operational parameters. This\r
+                       feature may be unsupported. Type EFI_SIMPLE_NETWORK_MODE\r
+                       is defined in the EFI_SIMPLE_NETWORK_PROTOCOL.\r
\r
+  @retval EFI_SUCCESS           The operation completed successfully.\r
+  @retval EFI_INVALID_PARAMETER This is NULL.\r
+  @retval EFI_UNSUPPORTED       The requested feature is unsupported in this\r
+                                MNP implementation.\r
+  @retval EFI_NOT_STARTED       This MNP child driver instance has not been\r
+                                configured. The default values are returned in\r
+                                MnpConfigData if it is not NULL.\r
+  @retval Other                 The mode data could not be read.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpGetModeData (\r
   IN  EFI_MANAGED_NETWORK_PROTOCOL     *This,\r
-  OUT EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData OPTIONAL,\r
-  OUT EFI_SIMPLE_NETWORK_MODE          *SnpModeData OPTIONAL\r
+  OUT EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData, OPTIONAL\r
+  OUT EFI_SIMPLE_NETWORK_MODE          *SnpModeData    OPTIONAL\r
   );\r
 \r
+/**\r
+  Sets or clears the operational parameters for the MNP child driver. \r
+   \r
+  The Configure() function is used to set, change, or reset the operational \r
+  parameters for the MNP child driver instance. Until the operational parameters\r
+  have been set, no network traffic can be sent or received by this MNP child\r
+  driver instance. Once the operational parameters have been reset, no more\r
+  traffic can be sent or received until the operational parameters have been set\r
+  again.\r
+  Each MNP child driver instance can be started and stopped independently of\r
+  each other by setting or resetting their receive filter settings with the\r
+  Configure() function.\r
+  After any successful call to Configure(), the MNP child driver instance is\r
+  started. The internal periodic timer (if supported) is enabled. Data can be\r
+  transmitted and may be received if the receive filters have also been enabled.\r
+  Note: If multiple MNP child driver instances will receive the same packet\r
+  because of overlapping receive filter settings, then the first MNP child\r
+  driver instance will receive the original packet and additional instances will\r
+  receive copies of the original packet.\r
+  Note: Warning: Receive filter settings that overlap will consume extra\r
+  processor and/or DMA resources and degrade system and network performance.\r
+\r
+  @param  This             Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param  MnpConfigData    Pointer to configuration data that will be assigned\r
+                           to the MNP child driver instance. If NULL, the MNP\r
+                           child driver instance is reset to startup defaults\r
+                           and all pending transmit and receive requests are\r
+                           flushed. Type EFI_MANAGED_NETWORK_CONFIG_DATA is\r
+                           defined in\r
+                           EFI_MANAGED_NETWORK_PROTOCOL.GetModeData().\r
+\r
+  @retval EFI_SUCCESS            The operation completed successfully.\r
+  @retval EFI_INVALID_PARAMETER  One or more of the following conditions is\r
+                                 TRUE:\r
+                                 * This is NULL.\r
+                                 * MnpConfigData.ProtocolTypeFilter is not\r
+                                   valid.\r
+                                 The operational data for the MNP child driver\r
+                                 instance is unchanged.\r
+  @retval EFI_OUT_OF_RESOURCES   Required system resources (usually memory)\r
+                                 could not be allocated.\r
+                                 The MNP child driver instance has been reset to\r
+                                 startup defaults.\r
+  @retval EFI_UNSUPPORTED        The requested feature is unsupported in\r
+                                 this [MNP] implementation. The operational data\r
+                                 for the MNP child driver instance is unchanged.\r
+  @retval EFI_DEVICE_ERROR       An unexpected network or system error\r
+                                 occurred. The MNP child driver instance has\r
+                                 been reset to startup defaults.\r
+  @retval Other                  The MNP child driver instance has been reset to\r
+                                 startup defaults.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpConfigure (\r
@@ -227,6 +490,36 @@ MnpConfigure (
   IN EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData OPTIONAL\r
   );\r
 \r
+/**\r
+  Translates an IP multicast address to a hardware (MAC) multicast address. This \r
+  function may be unsupported in some MNP implementations. \r
+   \r
+  The McastIpToMac() function translates an IP multicast address to a hardware\r
+  (MAC) multicast address. This function may be implemented by calling the\r
+  underlying EFI_SIMPLE_NETWORK.MCastIpToMac() function, which may also be\r
+  unsupported in some MNP implementations.\r
+\r
+  @param This       Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param Ipv6Flag   Set to TRUE to if IpAddress is an IPv6 multicast address.\r
+                    Set to FALSE if IpAddress is an IPv4 multicast address.\r
+  @param IpAddress  Pointer to the multicast IP address (in network byte order)\r
+                    to convert.\r
+  @param MacAddress Pointer to the resulting multicast MAC address. \r
+\r
+  @retval EFI_SUCCESS           The operation completed successfully.\r
+  @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE:\r
+                                 * This is NULL.\r
+                                 * IpAddress is NULL.\r
+                                 * IpAddress is not a valid multicast IP\r
+                                   address.\r
+                                 * MacAddress is NULL.\r
+  @retval EFI_NOT_STARTED       This MNP child driver instance has not been\r
+                                configured.\r
+  @retval EFI_UNSUPPORTED       The requested feature is unsupported in this\r
+                                MNP implementation.\r
+  @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.\r
+  @retval Other                 The address could not be converted.\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpMcastIpToMac (\r
@@ -236,6 +529,42 @@ MnpMcastIpToMac (
   OUT EFI_MAC_ADDRESS               *MacAddress\r
   );\r
 \r
+/**\r
+  Enables and disables receive filters for multicast address. This function may \r
+  be unsupported in some MNP implementations.\r
+   \r
+  The Groups() function only adds and removes multicast MAC addresses from the \r
+  filter list. The MNP driver does not transmit or process Internet Group\r
+  Management Protocol (IGMP) packets. If JoinFlag is FALSE and MacAddress is\r
+  NULL, then all joined groups are left.\r
+   \r
+  @param  This        Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param  JoinFlag    Set to TRUE to join this multicast group.\r
+                      Set to FALSE to leave this multicast group.\r
+  @param  MacAddress  Pointer to the multicast MAC group (address) to join or\r
+                      leave.\r
+\r
+  @retval EFI_SUCCESS           The requested operation completed successfully.\r
+  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+                                * This is NULL.\r
+                                * JoinFlag is TRUE and MacAddress is NULL.\r
+                                * MacAddress is not a valid multicast MAC\r
+                                  address.\r
+                                * The MNP multicast group settings are\r
+                                  unchanged.\r
+  @retval EFI_NOT_STARTED       This MNP child driver instance has not been\r
+                                configured.\r
+  @retval EFI_ALREADY_STARTED   The supplied multicast group is already joined.\r
+  @retval EFI_NOT_FOUND         The supplied multicast group is not joined.\r
+  @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.\r
+                                The MNP child driver instance has been reset to\r
+                                startup defaults.\r
+  @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP\r
+                                implementation.\r
+  @retval Other                 The requested operation could not be completed.\r
+                                The MNP multicast group settings are unchanged.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpGroups (\r
@@ -244,6 +573,61 @@ MnpGroups (
   IN EFI_MAC_ADDRESS               *MacAddress OPTIONAL\r
   );\r
 \r
+/**\r
+  Places asynchronous outgoing data packets into the transmit queue.\r
+   \r
+  The Transmit() function places a completion token into the transmit packet \r
+  queue. This function is always asynchronous.\r
+  The caller must fill in the Token.Event and Token.TxData fields in the\r
+  completion token, and these fields cannot be NULL. When the transmit operation\r
+  completes, the MNP updates the Token.Status field and the Token.Event is\r
+  signaled.\r
+  Note: There may be a performance penalty if the packet needs to be\r
+  defragmented before it can be transmitted by the network device. Systems in\r
+  which performance is critical should review the requirements and features of\r
+  the underlying communications device and drivers.\r
\r
\r
+  @param  This    Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param  Token   Pointer to a token associated with the transmit data\r
+                  descriptor. Type EFI_MANAGED_NETWORK_COMPLETION_TOKEN is\r
+                  defined in "Related Definitions" below.\r
+\r
+  @retval EFI_SUCCESS            The transmit completion token was cached.\r
+  @retval EFI_NOT_STARTED        This MNP child driver instance has not been\r
+                                 configured.\r
+  @retval EFI_INVALID_PARAMETER  One or more of the following conditions is\r
+                                 TRUE:\r
+                                 * This is NULL.\r
+                                 * Token is NULL.\r
+                                 * Token.Event is NULL.\r
+                                 * Token.TxData is NULL.\r
+                                 * Token.TxData.DestinationAddress is not\r
+                                   NULL and Token.TxData.HeaderLength is zero.\r
+                                 * Token.TxData.FragmentCount is zero.\r
+                                 * (Token.TxData.HeaderLength +\r
+                                   Token.TxData.DataLength) is not equal to the\r
+                                   sum of the\r
+                                   Token.TxData.FragmentTable[].FragmentLength\r
+                                   fields.\r
+                                 * One or more of the\r
+                                   Token.TxData.FragmentTable[].FragmentLength\r
+                                   fields is zero.\r
+                                 * One or more of the\r
+                                   Token.TxData.FragmentTable[].FragmentBufferfields\r
+                                   is NULL.\r
+                                 * Token.TxData.DataLength is greater than MTU.\r
+  @retval EFI_ACCESS_DENIED      The transmit completion token is already in the\r
+                                 transmit queue.\r
+  @retval EFI_OUT_OF_RESOURCES   The transmit data could not be queued due to a\r
+                                 lack of system resources (usually memory). \r
+  @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.\r
+                                 The MNP child driver instance has been reset to\r
+                                 startup defaults.\r
+  @retval EFI_NOT_READY          The transmit request could not be queued because\r
+                                 the transmit queue is full.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpTransmit (\r
@@ -251,6 +635,35 @@ MnpTransmit (
   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token\r
   );\r
 \r
+/**\r
+  Aborts an asynchronous transmit or receive request. \r
+   \r
+  The Cancel() function is used to abort a pending transmit or receive request.\r
+  If the token is in the transmit or receive request queues, after calling this\r
+  function, Token.Status will be set to EFI_ABORTED and then Token.Event will be\r
+  signaled. If the token is not in one of the queues, which usually means that\r
+  the asynchronous operation has completed, this function will not signal the\r
+  token and EFI_NOT_FOUND is returned.\r
+\r
+  @param  This     Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param  Token    Pointer to a token that has been issued by\r
+                   EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or\r
+                   EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If NULL, all pending\r
+                   tokens are aborted.\r
+\r
+  @retval EFI_SUCCESS            The asynchronous I/O request was aborted and\r
+                                 Token.Event was signaled. When Token is NULL,\r
+                                 all pending requests were aborted and their\r
+                                 events were signaled.\r
+  @retval EFI_NOT_STARTED        This MNP child driver instance has not been\r
+                                 configured.\r
+  @retval EFI_INVALID_PARAMETER  This is NULL.\r
+  @retval EFI_NOT_FOUND          When Token is not NULL, the asynchronous I/O\r
+                                 request was not found in the transmit or\r
+                                 receive queue. It has either completed or was\r
+                                 not issued by Transmit() and Receive().\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpCancel (\r
@@ -258,6 +671,41 @@ MnpCancel (
   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token OPTIONAL\r
   );\r
 \r
+/**\r
+  Places an asynchronous receiving request into the receiving queue.\r
+   \r
+  The Receive() function places a completion token into the receive packet \r
+  queue. This function is always asynchronous.\r
+  The caller must fill in the Token.Event field in the completion token, and\r
+  this field cannot be NULL. When the receive operation completes, the MNP\r
+  updates the Token.Status and Token.RxData fields and the Token.Event is\r
+  signaled.\r
+   \r
+  @param  This          Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param  Token         Pointer to a token associated with the receive\r
+                        data descriptor. Type\r
+                        EFI_MANAGED_NETWORK_COMPLETION_TOKEN is defined in\r
+                        EFI_MANAGED_NETWORK_PROTOCOL.Transmit().\r
+\r
+  @retval EFI_SUCCESS            The receive completion token was cached.\r
+  @retval EFI_NOT_STARTED        This MNP child driver instance has not been\r
+                                 configured.\r
+  @retval EFI_INVALID_PARAMETER  One or more of the following conditions is\r
+                                 TRUE:\r
+                                 * This is NULL.\r
+                                 * Token is NULL.\r
+                                 * Token.Event is NULL\r
+  @retval EFI_OUT_OF_RESOURCES   The transmit data could not be queued due to a\r
+                                 lack of system resources (usually memory).\r
+  @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.\r
+                                 The MNP child driver instance has been reset to\r
+                                 startup defaults.\r
+  @retval EFI_ACCESS_DENIED      The receive completion token was already in the\r
+                                 receive queue.\r
+  @retval EFI_NOT_READY          The receive request could not be queued because\r
+                                 the receive queue is full.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpReceive (\r
@@ -265,6 +713,32 @@ MnpReceive (
   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *Token\r
   );\r
 \r
+/**\r
+  Polls for incoming data packets and processes outgoing data packets. \r
+   \r
+  The Poll() function can be used by network drivers and applications to \r
+  increase the rate that data packets are moved between the communications\r
+  device and the transmit and receive queues.\r
+  Normally, a periodic timer event internally calls the Poll() function. But, in\r
+  some systems, the periodic timer event may not call Poll() fast enough to\r
+  transmit and/or receive all data packets without missing packets. Drivers and\r
+  applications that are experiencing packet loss should try calling the Poll()\r
+  function more often.\r
+\r
+  @param  This            Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+\r
+  @retval EFI_SUCCESS      Incoming or outgoing data was processed.\r
+  @retval EFI_NOT_STARTED  This MNP child driver instance has not been\r
+                           configured.\r
+  @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The\r
+                           MNP child driver instance has been reset to startup\r
+                           defaults.\r
+  @retval EFI_NOT_READY    No incoming or outgoing data was processed. Consider\r
+                           increasing the polling rate.\r
+  @retval EFI_TIMEOUT      Data was dropped out of the transmit and/or receive\r
+                           queue. Consider increasing the polling rate.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpPoll (\r
index 13bf552..0945c64 100644 (file)
@@ -124,8 +124,6 @@ MnpIsValidTxToken (
   @param  PktLen                Pointer to a UINT32 variable used to record the\r
                                 packet's length.\r
 \r
-  @return None.\r
-\r
 **/\r
 VOID\r
 MnpBuildTxPacket (\r
@@ -434,8 +432,6 @@ MnpDeliverPacket (
   @param  Event                 The event this notify function registered to.\r
   @param  Context               Pointer to the context data registerd to the Event.\r
 \r
-  @return None.\r
-\r
 **/\r
 VOID\r
 EFIAPI\r
@@ -1007,9 +1003,7 @@ EXIT:
   @param  Event                 The event this notify function registered to.\r
   @param  Context               Pointer to the context data registered to the\r
                                 event.\r
-\r
-  @return None.\r
-\r
+   \r
 **/\r
 VOID\r
 EFIAPI\r
index 95a4b67..ea05532 100644 (file)
@@ -27,27 +27,36 @@ Abstract:
 \r
 \r
 /**\r
-  Get configuration data of this instance.\r
-\r
-  @param  This                   Pointer to the Managed Network Protocol.\r
-  @param  MnpConfigData          Pointer to strorage for MNP operational\r
-                                 parameters.\r
-  @param  SnpModeData            Pointer to strorage for SNP operational\r
-                                 parameters.\r
-\r
-  @retval EFI_SUCCESS            The operation completed successfully.\r
-  @retval EFI_INVALID_PARAMETER  This is NULL.\r
-  @retval EFI_NOT_STARTED        This MNP child driver instance has not been\r
-                                 configured The default values are returned in\r
-                                 MnpConfigData if it is not NULL.\r
+  Returns the operational parameters for the current MNP child driver. May also\r
+  support returning the underlying SNP driver mode data.   \r
+   \r
+  The GetModeData() function is used to read the current mode data (operational\r
+  parameters) from the MNP or the underlying SNP. \r
+\r
+  @param This          Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param MnpConfigData Pointer to storage for MNP operational parameters. Type\r
+                       EFI_MANAGED_NETWORK_CONFIG_DATA is defined in "Related\r
+                       Definitions" below.\r
+  @param SnpModeData   Pointer to storage for SNP operational parameters. This\r
+                       feature may be unsupported. Type EFI_SIMPLE_NETWORK_MODE\r
+                       is defined in the EFI_SIMPLE_NETWORK_PROTOCOL.\r
\r
+  @retval EFI_SUCCESS           The operation completed successfully.\r
+  @retval EFI_INVALID_PARAMETER This is NULL.\r
+  @retval EFI_UNSUPPORTED       The requested feature is unsupported in this\r
+                                MNP implementation.\r
+  @retval EFI_NOT_STARTED       This MNP child driver instance has not been\r
+                                configured. The default values are returned in\r
+                                MnpConfigData if it is not NULL.\r
+  @retval Other                 The mode data could not be read.\r
 \r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
 MnpGetModeData (\r
   IN  EFI_MANAGED_NETWORK_PROTOCOL     *This,\r
-  OUT EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData OPTIONAL,\r
-  OUT EFI_SIMPLE_NETWORK_MODE          *SnpModeData OPTIONAL\r
+  OUT EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData, OPTIONAL\r
+  OUT EFI_SIMPLE_NETWORK_MODE          *SnpModeData    OPTIONAL\r
   )\r
 {\r
   MNP_INSTANCE_DATA           *Instance;\r
@@ -92,22 +101,54 @@ MnpGetModeData (
 \r
 \r
 /**\r
-  Set or clear the operational parameters for the MNP child driver.\r
-\r
-  @param  This                   Pointer to the Managed Network Protocol.\r
-  @param  MnpConfigData          Pointer to the configuration data that will be\r
-                                 assigned to the MNP child driver instance. If\r
-                                 NULL, the MNP child driver instance is reset to\r
-                                 startup defaults and all pending transmit and\r
-                                 receive requests are flushed.\r
+  Sets or clears the operational parameters for the MNP child driver. \r
+   \r
+  The Configure() function is used to set, change, or reset the operational \r
+  parameters for the MNP child driver instance. Until the operational parameters\r
+  have been set, no network traffic can be sent or received by this MNP child\r
+  driver instance. Once the operational parameters have been reset, no more\r
+  traffic can be sent or received until the operational parameters have been set\r
+  again.\r
+  Each MNP child driver instance can be started and stopped independently of\r
+  each other by setting or resetting their receive filter settings with the\r
+  Configure() function.\r
+  After any successful call to Configure(), the MNP child driver instance is\r
+  started. The internal periodic timer (if supported) is enabled. Data can be\r
+  transmitted and may be received if the receive filters have also been enabled.\r
+  Note: If multiple MNP child driver instances will receive the same packet\r
+  because of overlapping receive filter settings, then the first MNP child\r
+  driver instance will receive the original packet and additional instances will\r
+  receive copies of the original packet.\r
+  Note: Warning: Receive filter settings that overlap will consume extra\r
+  processor and/or DMA resources and degrade system and network performance.\r
+\r
+  @param  This             Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param  MnpConfigData    Pointer to configuration data that will be assigned\r
+                           to the MNP child driver instance. If NULL, the MNP\r
+                           child driver instance is reset to startup defaults\r
+                           and all pending transmit and receive requests are\r
+                           flushed. Type EFI_MANAGED_NETWORK_CONFIG_DATA is\r
+                           defined in\r
+                           EFI_MANAGED_NETWORK_PROTOCOL.GetModeData().\r
 \r
   @retval EFI_SUCCESS            The operation completed successfully.\r
-  @retval EFI_INVALID_PARAMETER  One or more parameter is invalid.\r
-  @retval EFI_OUT_OF_RESOURCES   Required system resources (usually memory) could\r
-                                 not be allocated.\r
-  @retval EFI_UNSUPPORTED        EnableReceiveTimestamps is TRUE, this\r
-                                 implementation doesn't support it.\r
-  @retval EFI_DEVICE_ERROR       An unexpected network or system error occurred.\r
+  @retval EFI_INVALID_PARAMETER  One or more of the following conditions is\r
+                                 TRUE:\r
+                                 * This is NULL.\r
+                                 * MnpConfigData.ProtocolTypeFilter is not\r
+                                   valid.\r
+                                 The operational data for the MNP child driver\r
+                                 instance is unchanged.\r
+  @retval EFI_OUT_OF_RESOURCES   Required system resources (usually memory)\r
+                                 could not be allocated.\r
+                                 The MNP child driver instance has been reset to\r
+                                 startup defaults.\r
+  @retval EFI_UNSUPPORTED        The requested feature is unsupported in\r
+                                 this [MNP] implementation. The operational data\r
+                                 for the MNP child driver instance is unchanged.\r
+  @retval EFI_DEVICE_ERROR       An unexpected network or system error\r
+                                 occurred. The MNP child driver instance has\r
+                                 been reset to startup defaults.\r
   @retval Other                  The MNP child driver instance has been reset to\r
                                  startup defaults.\r
 \r
@@ -156,24 +197,34 @@ ON_EXIT:
 \r
 \r
 /**\r
-  Translate a multicast IP address to a multicast hardware (MAC) address.\r
-\r
-  @param  This                   Pointer to the Managed Network Protocol.\r
-  @param  Ipv6Flag               Set to TRUE if IpAddress is an IPv6 multicast\r
-                                 address. Set to FALSE if IpAddress is an IPv4\r
-                                 multicast address.\r
-  @param  IpAddress              Pointer to the multicast IP address to convert.\r
-  @param  MacAddress             Pointer to the resulting multicast MAC address.\r
-\r
-  @retval EFI_SUCCESS            The operation completed successfully.\r
-  @retval EFI_INVALID_PARAMETER  One or more parameter is invalid.\r
-  @retval EFI_NOT_STARTED        This MNP child driver instance has not been\r
-                                 configured.\r
-  @retval EFI_UNSUPPORTED        Ipv6Flag is TRUE, this implementation doesn't\r
-                                 supported it.\r
-  @retval EFI_DEVICE_ERROR       An unexpected network or system error occurred.\r
-  @retval Other                  The address could not be converted.\r
-\r
+  Translates an IP multicast address to a hardware (MAC) multicast address. This \r
+  function may be unsupported in some MNP implementations. \r
+   \r
+  The McastIpToMac() function translates an IP multicast address to a hardware\r
+  (MAC) multicast address. This function may be implemented by calling the\r
+  underlying EFI_SIMPLE_NETWORK.MCastIpToMac() function, which may also be\r
+  unsupported in some MNP implementations.\r
+\r
+  @param This       Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param Ipv6Flag   Set to TRUE to if IpAddress is an IPv6 multicast address.\r
+                    Set to FALSE if IpAddress is an IPv4 multicast address.\r
+  @param IpAddress  Pointer to the multicast IP address (in network byte order)\r
+                    to convert.\r
+  @param MacAddress Pointer to the resulting multicast MAC address. \r
+\r
+  @retval EFI_SUCCESS           The operation completed successfully.\r
+  @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE:\r
+                                 * This is NULL.\r
+                                 * IpAddress is NULL.\r
+                                 * IpAddress is not a valid multicast IP\r
+                                   address.\r
+                                 * MacAddress is NULL.\r
+  @retval EFI_NOT_STARTED       This MNP child driver instance has not been\r
+                                configured.\r
+  @retval EFI_UNSUPPORTED       The requested feature is unsupported in this\r
+                                MNP implementation.\r
+  @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.\r
+  @retval Other                 The address could not be converted.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -252,25 +303,40 @@ ON_EXIT:
   return Status;\r
 }\r
 \r
-\r
 /**\r
-  Enable or disable receie filters for multicast address.\r
-\r
-  @param  This                   Pointer to the Managed Network Protocol.\r
-  @param  JoinFlag               Set to TRUE to join this multicast group. Set to\r
-                                 FALSE to leave this multicast group.\r
-  @param  MacAddress             Pointer to the multicast MAC group (address) to\r
-                                 join or leave.\r
-\r
-  @retval EFI_SUCCESS            The operation completed successfully.\r
-  @retval EFI_INVALID_PARAMETER  One or more parameter is invalid\r
-  @retval EFI_NOT_STARTED        This MNP child driver instance has not been\r
-                                 configured.\r
-  @retval EFI_ALREADY_STARTED    The supplied multicast group is already joined.\r
-  @retval EFI_NOT_FOUND          The supplied multicast group is not joined.\r
-  @retval EFI_DEVICE_ERROR       An unexpected network or system error occurred.\r
-  @retval Other                  The requested operation could not be completed.\r
-                                 The MNP multicast group settings are unchanged.\r
+  Enables and disables receive filters for multicast address. This function may \r
+  be unsupported in some MNP implementations.\r
+   \r
+  The Groups() function only adds and removes multicast MAC addresses from the \r
+  filter list. The MNP driver does not transmit or process Internet Group\r
+  Management Protocol (IGMP) packets. If JoinFlag is FALSE and MacAddress is\r
+  NULL, then all joined groups are left.\r
+   \r
+  @param  This        Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param  JoinFlag    Set to TRUE to join this multicast group.\r
+                      Set to FALSE to leave this multicast group.\r
+  @param  MacAddress  Pointer to the multicast MAC group (address) to join or\r
+                      leave.\r
+\r
+  @retval EFI_SUCCESS           The requested operation completed successfully.\r
+  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+                                * This is NULL.\r
+                                * JoinFlag is TRUE and MacAddress is NULL.\r
+                                * MacAddress is not a valid multicast MAC\r
+                                  address.\r
+                                * The MNP multicast group settings are\r
+                                  unchanged.\r
+  @retval EFI_NOT_STARTED       This MNP child driver instance has not been\r
+                                configured.\r
+  @retval EFI_ALREADY_STARTED   The supplied multicast group is already joined.\r
+  @retval EFI_NOT_FOUND         The supplied multicast group is not joined.\r
+  @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.\r
+                                The MNP child driver instance has been reset to\r
+                                startup defaults.\r
+  @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP\r
+                                implementation.\r
+  @retval Other                 The requested operation could not be completed.\r
+                                The MNP multicast group settings are unchanged.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -383,22 +449,54 @@ ON_EXIT:
   return Status;\r
 }\r
 \r
-\r
 /**\r
-  Place an outgoing packet into the transmit queue.\r
-\r
-  @param  This                   Pointer to the Managed Network Protocol.\r
-  @param  Token                  Pointer to a token associated with the transmit\r
-                                 data descriptor.\r
-\r
-  @retval EFI_SUCCESS            The operation completed successfully.\r
-  @retval EFI_INVALID_PARAMETER  One or more parameter is invalid\r
+  Places asynchronous outgoing data packets into the transmit queue.\r
+   \r
+  The Transmit() function places a completion token into the transmit packet \r
+  queue. This function is always asynchronous.\r
+  The caller must fill in the Token.Event and Token.TxData fields in the\r
+  completion token, and these fields cannot be NULL. When the transmit operation\r
+  completes, the MNP updates the Token.Status field and the Token.Event is\r
+  signaled.\r
+  Note: There may be a performance penalty if the packet needs to be\r
+  defragmented before it can be transmitted by the network device. Systems in\r
+  which performance is critical should review the requirements and features of\r
+  the underlying communications device and drivers.\r
\r
\r
+  @param  This    Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param  Token   Pointer to a token associated with the transmit data\r
+                  descriptor. Type EFI_MANAGED_NETWORK_COMPLETION_TOKEN is\r
+                  defined in "Related Definitions" below.\r
+\r
+  @retval EFI_SUCCESS            The transmit completion token was cached.\r
   @retval EFI_NOT_STARTED        This MNP child driver instance has not been\r
                                  configured.\r
+  @retval EFI_INVALID_PARAMETER  One or more of the following conditions is\r
+                                 TRUE:\r
+                                 * This is NULL.\r
+                                 * Token is NULL.\r
+                                 * Token.Event is NULL.\r
+                                 * Token.TxData is NULL.\r
+                                 * Token.TxData.DestinationAddress is not\r
+                                   NULL and Token.TxData.HeaderLength is zero.\r
+                                 * Token.TxData.FragmentCount is zero.\r
+                                 * (Token.TxData.HeaderLength +\r
+                                   Token.TxData.DataLength) is not equal to the\r
+                                   sum of the\r
+                                   Token.TxData.FragmentTable[].FragmentLength\r
+                                   fields.\r
+                                 * One or more of the\r
+                                   Token.TxData.FragmentTable[].FragmentLength\r
+                                   fields is zero.\r
+                                 * One or more of the\r
+                                   Token.TxData.FragmentTable[].FragmentBufferfields\r
+                                   is NULL.\r
+                                 * Token.TxData.DataLength is greater than MTU.\r
   @retval EFI_ACCESS_DENIED      The transmit completion token is already in the\r
                                  transmit queue.\r
   @retval EFI_OUT_OF_RESOURCES   The transmit data could not be queued due to a\r
-                                 lack of system resources (usually memory).\r
+                                 lack of system resources (usually memory). \r
   @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.\r
                                  The MNP child driver instance has been reset to\r
                                  startup defaults.\r
@@ -464,17 +562,29 @@ ON_EXIT:
 \r
 \r
 /**\r
-  Place an asynchronous receiving request into the receiving queue.\r
-\r
-  @param  This                   Pointer to the EFI_MANAGED_NETWORK_PROTOCOL\r
-                                 instance.\r
-  @param  Token                  Pointer to a token associated with the receive\r
-                                 data descriptor.\r
+  Places an asynchronous receiving request into the receiving queue.\r
+   \r
+  The Receive() function places a completion token into the receive packet \r
+  queue. This function is always asynchronous.\r
+  The caller must fill in the Token.Event field in the completion token, and\r
+  this field cannot be NULL. When the receive operation completes, the MNP\r
+  updates the Token.Status and Token.RxData fields and the Token.Event is\r
+  signaled.\r
+   \r
+  @param  This          Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param  Token         Pointer to a token associated with the receive\r
+                        data descriptor. Type\r
+                        EFI_MANAGED_NETWORK_COMPLETION_TOKEN is defined in\r
+                        EFI_MANAGED_NETWORK_PROTOCOL.Transmit().\r
 \r
   @retval EFI_SUCCESS            The receive completion token was cached.\r
   @retval EFI_NOT_STARTED        This MNP child driver instance has not been\r
                                  configured.\r
-  @retval EFI_INVALID_PARAMETER  One or more parameter is invalid.\r
+  @retval EFI_INVALID_PARAMETER  One or more of the following conditions is\r
+                                 TRUE:\r
+                                 * This is NULL.\r
+                                 * Token is NULL.\r
+                                 * Token.Event is NULL\r
   @retval EFI_OUT_OF_RESOURCES   The transmit data could not be queued due to a\r
                                  lack of system resources (usually memory).\r
   @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.\r
@@ -544,25 +654,33 @@ ON_EXIT:
   return Status;\r
 }\r
 \r
-\r
 /**\r
-  Abort a pending transmit or receive request.\r
-\r
-  @param  This                   Pointer to the EFI_MANAGED_NETWORK_PROTOCOL\r
-                                 instance.\r
-  @param  Token                  Pointer to a token that has been issued by\r
-                                 EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or\r
-                                 EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If NULL,\r
-                                 all pending tokens are aborted.\r
+  Aborts an asynchronous transmit or receive request. \r
+   \r
+  The Cancel() function is used to abort a pending transmit or receive request.\r
+  If the token is in the transmit or receive request queues, after calling this\r
+  function, Token.Status will be set to EFI_ABORTED and then Token.Event will be\r
+  signaled. If the token is not in one of the queues, which usually means that\r
+  the asynchronous operation has completed, this function will not signal the\r
+  token and EFI_NOT_FOUND is returned.\r
+\r
+  @param  This     Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+  @param  Token    Pointer to a token that has been issued by\r
+                   EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or\r
+                   EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If NULL, all pending\r
+                   tokens are aborted.\r
 \r
   @retval EFI_SUCCESS            The asynchronous I/O request was aborted and\r
-                                 Token->Event was signaled.\r
+                                 Token.Event was signaled. When Token is NULL,\r
+                                 all pending requests were aborted and their\r
+                                 events were signaled.\r
   @retval EFI_NOT_STARTED        This MNP child driver instance has not been\r
                                  configured.\r
   @retval EFI_INVALID_PARAMETER  This is NULL.\r
-  @retval EFI_NOT_FOUND          The asynchronous I/O request was not found in the\r
-                                 transmit or receive queue. It has either completed\r
-                                 or was not issued by Transmit() and Receive().\r
+  @retval EFI_NOT_FOUND          When Token is not NULL, the asynchronous I/O\r
+                                 request was not found in the transmit or\r
+                                 receive queue. It has either completed or was\r
+                                 not issued by Transmit() and Receive().\r
 \r
 **/\r
 EFI_STATUS\r
@@ -612,22 +730,30 @@ ON_EXIT:
   return Status;\r
 }\r
 \r
-\r
 /**\r
-  Poll the network interface to do transmit/receive work.\r
-\r
-  @param  This                   Pointer to the EFI_MANAGED_NETWORK_PROTOCOL\r
-                                 instance.\r
-\r
-  @retval EFI_SUCCESS            Incoming or outgoing data was processed.\r
-  @retval EFI_NOT_STARTED        This MNP child driver instance has not been\r
-                                 configured.\r
-  @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.\r
-                                 The MNP child driver instance has been reset to\r
-                                 startup defaults.\r
-  @retval EFI_NOT_READY          No incoming or outgoing data was processed.\r
-  @retval EFI_TIMEOUT            Data was dropped out of the transmit and/or\r
-                                 receive queue.\r
+  Polls for incoming data packets and processes outgoing data packets. \r
+   \r
+  The Poll() function can be used by network drivers and applications to \r
+  increase the rate that data packets are moved between the communications\r
+  device and the transmit and receive queues.\r
+  Normally, a periodic timer event internally calls the Poll() function. But, in\r
+  some systems, the periodic timer event may not call Poll() fast enough to\r
+  transmit and/or receive all data packets without missing packets. Drivers and\r
+  applications that are experiencing packet loss should try calling the Poll()\r
+  function more often.\r
+\r
+  @param  This            Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.\r
+\r
+  @retval EFI_SUCCESS      Incoming or outgoing data was processed.\r
+  @retval EFI_NOT_STARTED  This MNP child driver instance has not been\r
+                           configured.\r
+  @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The\r
+                           MNP child driver instance has been reset to startup\r
+                           defaults.\r
+  @retval EFI_NOT_READY    No incoming or outgoing data was processed. Consider\r
+                           increasing the polling rate.\r
+  @retval EFI_TIMEOUT      Data was dropped out of the transmit and/or receive\r
+                           queue. Consider increasing the polling rate.\r
 \r
 **/\r
 EFI_STATUS\r