sync comments, fix function header, rename variable name to follow coding style.
[mirror_edk2.git] / MdeModulePkg / Universal / Network / SnpDxe / Get_status.c
index 9eaafb9..17078c8 100644 (file)
@@ -1,21 +1,16 @@
 /** @file\r
-Copyright (c) 2004 - 2007, Intel Corporation\r
-All rights reserved. This program and the accompanying materials\r
-are licensed and made available under the terms and conditions of the BSD License\r
-which accompanies this distribution.  The full text of the license may be found at\r
-http://opensource.org/licenses/bsd-license.php\r
+               Implementation of reading the current interrupt status and recycled transmit\r
+         buffer status from a network interface.\r
+\r
+Copyright (c) 2004 - 2007, Intel Corporation. <BR> \r
+All rights reserved. This program and the accompanying materials are licensed \r
+and made available under the terms and conditions of the BSD License which \r
+accompanies this distribution. The full text of the license may be found at \r
+http://opensource.org/licenses/bsd-license.php \r
 \r
 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
-Module name:\r
-  get_status.c\r
-\r
-Abstract:\r
-\r
-Revision history:\r
-  2000-Feb-03 M(f)J   Genesis.\r
-\r
 **/\r
 \r
 #include "Snp.h"\r
@@ -24,7 +19,7 @@ Revision history:
   this routine calls undi to get the status of the interrupts, get the list of\r
   transmit buffers that completed transmitting!\r
 \r
-  @param  snp                     pointer to snp driver structure\r
+  @param  Snp                     pointer to snp driver structure\r
   @param  InterruptStatusPtr      a non null pointer gets the interrupt status\r
   @param  TransmitBufferListPtrs  a non null ointer gets the list of pointers of\r
                                   previously  transmitted buffers whose\r
@@ -33,56 +28,56 @@ Revision history:
 \r
 **/\r
 EFI_STATUS\r
-pxe_getstatus (\r
-  SNP_DRIVER *snp,\r
+PxeGetStatus (\r
+  SNP_DRIVER *Snp,\r
   UINT32     *InterruptStatusPtr,\r
   VOID       **TransmitBufferListPtr\r
   )\r
 {\r
-  PXE_DB_GET_STATUS *db;\r
+  PXE_DB_GET_STATUS *Db;\r
   UINT16            InterruptFlags;\r
 \r
-  db                = snp->db;\r
-  snp->cdb.OpCode   = PXE_OPCODE_GET_STATUS;\r
+  Db                = Snp->Db;\r
+  Snp->Cdb.OpCode   = PXE_OPCODE_GET_STATUS;\r
 \r
-  snp->cdb.OpFlags  = 0;\r
+  Snp->Cdb.OpFlags  = 0;\r
 \r
   if (TransmitBufferListPtr != NULL) {\r
-    snp->cdb.OpFlags |= PXE_OPFLAGS_GET_TRANSMITTED_BUFFERS;\r
+    Snp->Cdb.OpFlags |= PXE_OPFLAGS_GET_TRANSMITTED_BUFFERS;\r
   }\r
 \r
   if (InterruptStatusPtr != NULL) {\r
-    snp->cdb.OpFlags |= PXE_OPFLAGS_GET_INTERRUPT_STATUS;\r
+    Snp->Cdb.OpFlags |= PXE_OPFLAGS_GET_INTERRUPT_STATUS;\r
   }\r
 \r
-  snp->cdb.CPBsize  = PXE_CPBSIZE_NOT_USED;\r
-  snp->cdb.CPBaddr  = PXE_CPBADDR_NOT_USED;\r
+  Snp->Cdb.CPBsize  = PXE_CPBSIZE_NOT_USED;\r
+  Snp->Cdb.CPBaddr  = PXE_CPBADDR_NOT_USED;\r
 \r
   //\r
   // size DB for return of one buffer\r
   //\r
-  snp->cdb.DBsize = (UINT16) (((UINT16) (sizeof (PXE_DB_GET_STATUS)) - (UINT16) (sizeof db->TxBuffer)) + (UINT16) (sizeof db->TxBuffer[0]));\r
+  Snp->Cdb.DBsize     = (UINT16) ((sizeof (PXE_DB_GET_STATUS) - sizeof (Db->TxBuffer)) + sizeof (Db->TxBuffer[0]));\r
 \r
-  snp->cdb.DBaddr     = (UINT64)(UINTN) db;\r
+  Snp->Cdb.DBaddr     = (UINT64)(UINTN) Db;\r
 \r
-  snp->cdb.StatCode   = PXE_STATCODE_INITIALIZE;\r
-  snp->cdb.StatFlags  = PXE_STATFLAGS_INITIALIZE;\r
-  snp->cdb.IFnum      = snp->if_num;\r
-  snp->cdb.Control    = PXE_CONTROL_LAST_CDB_IN_LIST;\r
+  Snp->Cdb.StatCode   = PXE_STATCODE_INITIALIZE;\r
+  Snp->Cdb.StatFlags  = PXE_STATFLAGS_INITIALIZE;\r
+  Snp->Cdb.IFnum      = Snp->IfNum;\r
+  Snp->Cdb.Control    = PXE_CONTROL_LAST_CDB_IN_LIST;\r
 \r
   //\r
   // Issue UNDI command and check result.\r
   //\r
-  DEBUG ((EFI_D_NET, "\nsnp->undi.get_status()  "));\r
+  DEBUG ((EFI_D_NET, "\nSnp->undi.get_status()  "));\r
 \r
-  (*snp->issue_undi32_command) ((UINT64)(UINTN) &snp->cdb);\r
+  (*Snp->IssueUndi32Command) ((UINT64)(UINTN) &Snp->Cdb);\r
 \r
-  if (snp->cdb.StatCode != EFI_SUCCESS) {\r
+  if (Snp->Cdb.StatCode != EFI_SUCCESS) {\r
     DEBUG (\r
       (EFI_D_NET,\r
-      "\nsnp->undi.get_status()  %xh:%xh\n",\r
-      snp->cdb.StatFlags,\r
-      snp->cdb.StatFlags)\r
+      "\nSnp->undi.get_status()  %xh:%xh\n",\r
+      Snp->Cdb.StatFlags,\r
+      Snp->Cdb.StatFlags)\r
       );\r
 \r
     return EFI_DEVICE_ERROR;\r
@@ -91,23 +86,23 @@ pxe_getstatus (
   // report the values back..\r
   //\r
   if (InterruptStatusPtr != NULL) {\r
-    InterruptFlags      = (UINT16) (snp->cdb.StatFlags & PXE_STATFLAGS_GET_STATUS_INTERRUPT_MASK);\r
+    InterruptFlags      = (UINT16) (Snp->Cdb.StatFlags & PXE_STATFLAGS_GET_STATUS_INTERRUPT_MASK);\r
 \r
     *InterruptStatusPtr = 0;\r
 \r
-    if (InterruptFlags & PXE_STATFLAGS_GET_STATUS_RECEIVE) {\r
+    if ((InterruptFlags & PXE_STATFLAGS_GET_STATUS_RECEIVE) == PXE_STATFLAGS_GET_STATUS_RECEIVE) {\r
       *InterruptStatusPtr |= EFI_SIMPLE_NETWORK_RECEIVE_INTERRUPT;\r
     }\r
 \r
-    if (InterruptFlags & PXE_STATFLAGS_GET_STATUS_TRANSMIT) {\r
+    if ((InterruptFlags & PXE_STATFLAGS_GET_STATUS_TRANSMIT) == PXE_STATFLAGS_GET_STATUS_TRANSMIT) {\r
       *InterruptStatusPtr |= EFI_SIMPLE_NETWORK_TRANSMIT_INTERRUPT;\r
     }\r
 \r
-    if (InterruptFlags & PXE_STATFLAGS_GET_STATUS_COMMAND) {\r
+    if ((InterruptFlags & PXE_STATFLAGS_GET_STATUS_COMMAND) == PXE_STATFLAGS_GET_STATUS_COMMAND) {\r
       *InterruptStatusPtr |= EFI_SIMPLE_NETWORK_COMMAND_INTERRUPT;\r
     }\r
 \r
-    if (InterruptFlags & PXE_STATFLAGS_GET_STATUS_SOFTWARE) {\r
+    if ((InterruptFlags & PXE_STATFLAGS_GET_STATUS_SOFTWARE) == PXE_STATFLAGS_GET_STATUS_SOFTWARE) {\r
       *InterruptStatusPtr |= EFI_SIMPLE_NETWORK_COMMAND_INTERRUPT;\r
     }\r
 \r
@@ -116,58 +111,82 @@ pxe_getstatus (
   if (TransmitBufferListPtr != NULL) {\r
     *TransmitBufferListPtr =\r
       (\r
-        (snp->cdb.StatFlags & PXE_STATFLAGS_GET_STATUS_NO_TXBUFS_WRITTEN) ||\r
-        (snp->cdb.StatFlags & PXE_STATFLAGS_GET_STATUS_TXBUF_QUEUE_EMPTY)\r
-      ) ? 0 : (VOID *) (UINTN) db->TxBuffer[0];\r
+        (Snp->Cdb.StatFlags & PXE_STATFLAGS_GET_STATUS_NO_TXBUFS_WRITTEN) ||\r
+        (Snp->Cdb.StatFlags & PXE_STATFLAGS_GET_STATUS_TXBUF_QUEUE_EMPTY)\r
+      ) ? 0 : (VOID *) (UINTN) Db->TxBuffer[0];\r
 \r
   }\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r
-\r
 /**\r
-  This is the SNP interface routine for getting the status\r
-  This routine basically retrieves snp structure, checks the SNP state and\r
-  calls the pxe_getstatus routine to actually get the undi status\r
-\r
-  @param  this                    context pointer\r
-  @param  InterruptStatusPtr      a non null pointer gets the interrupt status\r
-  @param  TransmitBufferListPtrs  a non null ointer gets the list of pointers of\r
-                                  previously  transmitted buffers whose\r
-                                  transmission was completed  asynchrnously.\r
-\r
+  Reads the current interrupt status and recycled transmit buffer status from a\r
+  network interface.\r
+  \r
+  This function gets the current interrupt and recycled transmit buffer status \r
+  from the network interface. The interrupt status is returned as a bit mask in\r
+  InterruptStatus. If InterruptStatus is NULL, the interrupt status will not be\r
+  read. If TxBuf is not NULL, a recycled transmit buffer address will be retrieved.\r
+  If a recycled transmit buffer address is returned in TxBuf, then the buffer has\r
+  been successfully transmitted, and the status for that buffer is cleared. If\r
+  the status of the network interface is successfully collected, EFI_SUCCESS \r
+  will be returned. If the driver has not been initialized, EFI_DEVICE_ERROR will\r
+  be returned.\r
+\r
+  @param This            A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.\r
+  @param InterruptStatus A pointer to the bit mask of the currently active \r
+                         interrupts (see "Related Definitions"). If this is NULL,\r
+                         the interrupt status will not be read from the device.\r
+                         If this is not NULL, the interrupt status will be read\r
+                         from the device. When the interrupt status is read, it \r
+                         will also be cleared. Clearing the transmit interrupt does \r
+                         not empty the recycled transmit buffer array.\r
+  @param TxBuf           Recycled transmit buffer address. The network interface\r
+                         will not transmit if its internal recycled transmit \r
+                         buffer array is full. Reading the transmit buffer does\r
+                         not clear the transmit interrupt. If this is NULL, then\r
+                         the transmit buffer status will not be read. If there \r
+                         are no transmit buffers to recycle and TxBuf is not NULL, \r
+                         TxBuf will be set to NULL.\r
+\r
+  @retval EFI_SUCCESS           The status of the network interface was retrieved.\r
+  @retval EFI_NOT_STARTED       The network interface has not been started.\r
+  @retval EFI_INVALID_PARAMETER This parameter was NULL or did not point to a valid \r
+                                EFI_SIMPLE_NETWORK_PROTOCOL structure.\r
+  @retval EFI_DEVICE_ERROR      The command could not be sent to the network \r
+                                interface.\r
 \r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
-snp_undi32_get_status (\r
-  IN EFI_SIMPLE_NETWORK_PROTOCOL * this,\r
-  OUT UINT32                     *InterruptStatusPtr OPTIONAL,\r
-  OUT VOID                       **TransmitBufferListPtr OPTIONAL\r
+SnpUndi32GetStatus (\r
+  IN EFI_SIMPLE_NETWORK_PROTOCOL *This,\r
+  OUT UINT32                     *InterruptStatus, OPTIONAL\r
+  OUT VOID                       **TxBuf           OPTIONAL\r
   )\r
 {\r
-  SNP_DRIVER  *snp;\r
+  SNP_DRIVER  *Snp;\r
   EFI_TPL     OldTpl;\r
   EFI_STATUS  Status;\r
 \r
-  if (this == NULL) {\r
+  if (This == NULL) {\r
     return EFI_INVALID_PARAMETER;\r
   }\r
 \r
-  if (InterruptStatusPtr == NULL && TransmitBufferListPtr == NULL) {\r
+  if (InterruptStatus == NULL && TxBuf == NULL) {\r
     return EFI_INVALID_PARAMETER;\r
   }\r
 \r
-  snp = EFI_SIMPLE_NETWORK_DEV_FROM_THIS (this);\r
+  Snp = EFI_SIMPLE_NETWORK_DEV_FROM_THIS (This);\r
 \r
   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);\r
 \r
-  if (snp == NULL) {\r
+  if (Snp == NULL) {\r
     return EFI_DEVICE_ERROR;\r
   }\r
 \r
-  switch (snp->mode.State) {\r
+  switch (Snp->Mode.State) {\r
   case EfiSimpleNetworkInitialized:\r
     break;\r
 \r
@@ -180,7 +199,7 @@ snp_undi32_get_status (
     goto ON_EXIT;\r
   }\r
 \r
-  Status = pxe_getstatus (snp, InterruptStatusPtr, TransmitBufferListPtr);\r
+  Status = PxeGetStatus (Snp, InterruptStatus, TxBuf);\r
 \r
 ON_EXIT:\r
   gBS->RestoreTPL (OldTpl);\r