sync comments, fix function header, rename variable name to follow coding style.
[mirror_edk2.git] / MdeModulePkg / Universal / Network / SnpDxe / Nvdata.c
index 7d31d6d..4b9259f 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 and writing operations on the NVRAM device\r
+               attached to 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
-  nvdata.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,48 +19,47 @@ Revision history:
 /**\r
   This routine calls Undi to read the desired number of eeprom bytes.\r
 \r
-  @param  snp          pointer to the snp driver structure\r
-  @param  RegOffset    eeprom register value relative to the base address\r
-  @param  NumBytes     number of bytes to read\r
-  @param  BufferPtr    pointer where to read into\r
+  @param  Snp          pointer to the snp driver structure\r
+  @param  Offset       eeprom register value relative to the base address\r
+  @param  BufferSize   number of bytes to read\r
+  @param  Buffer       pointer where to read into\r
 \r
 \r
 **/\r
-STATIC\r
 EFI_STATUS\r
-pxe_nvdata_read (\r
-  IN SNP_DRIVER *snp,\r
-  IN UINTN      RegOffset,\r
-  IN UINTN      NumBytes,\r
-  IN OUT VOID   *BufferPtr\r
+PxeNvDataRead (\r
+  IN SNP_DRIVER *Snp,\r
+  IN UINTN      Offset,\r
+  IN UINTN      BufferSize,\r
+  IN OUT VOID   *Buffer\r
   )\r
 {\r
-  PXE_DB_NVDATA *db;\r
+  PXE_DB_NVDATA *Db;\r
 \r
-  db                  = snp->db;\r
-  snp->cdb.OpCode     = PXE_OPCODE_NVDATA;\r
+  Db                  = Snp->Db;\r
+  Snp->Cdb.OpCode     = PXE_OPCODE_NVDATA;\r
 \r
-  snp->cdb.OpFlags    = PXE_OPFLAGS_NVDATA_READ;\r
+  Snp->Cdb.OpFlags    = PXE_OPFLAGS_NVDATA_READ;\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
-  snp->cdb.DBsize     = sizeof (PXE_DB_NVDATA);\r
-  snp->cdb.DBaddr     = (UINT64)(UINTN) db;\r
+  Snp->Cdb.DBsize     = sizeof (PXE_DB_NVDATA);\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.nvdata ()  "));\r
 \r
-  (*snp->issue_undi32_command) ((UINT64)(UINTN) &snp->cdb);\r
+  (*Snp->IssueUndi32Command) ((UINT64)(UINTN) &Snp->Cdb);\r
 \r
-  switch (snp->cdb.StatCode) {\r
+  switch (Snp->Cdb.StatCode) {\r
   case PXE_STATCODE_SUCCESS:\r
     break;\r
 \r
@@ -73,8 +67,8 @@ pxe_nvdata_read (
     DEBUG (\r
       (EFI_D_NET,\r
       "\nsnp->undi.nvdata()  %xh:%xh\n",\r
-      snp->cdb.StatFlags,\r
-      snp->cdb.StatCode)\r
+      Snp->Cdb.StatFlags,\r
+      Snp->Cdb.StatCode)\r
       );\r
 \r
     return EFI_UNSUPPORTED;\r
@@ -83,61 +77,99 @@ pxe_nvdata_read (
     DEBUG (\r
       (EFI_D_NET,\r
       "\nsnp->undi.nvdata()  %xh:%xh\n",\r
-      snp->cdb.StatFlags,\r
-      snp->cdb.StatCode)\r
+      Snp->Cdb.StatFlags,\r
+      Snp->Cdb.StatCode)\r
       );\r
 \r
     return EFI_DEVICE_ERROR;\r
   }\r
 \r
-  CopyMem (BufferPtr, db->Data.Byte + RegOffset, NumBytes);\r
+  CopyMem (Buffer, Db->Data.Byte + Offset, BufferSize);\r
 \r
   return EFI_SUCCESS;\r
 }\r
 \r
 \r
 /**\r
-  This is an interface call provided by SNP.\r
+  Performs read and write operations on the NVRAM device attached to a network \r
+  interface.\r
+  \r
+  This function performs read and write operations on the NVRAM device attached \r
+  to a network interface. If ReadWrite is TRUE, a read operation is performed.\r
+  If ReadWrite is FALSE, a write operation is performed. Offset specifies the \r
+  byte offset at which to start either operation. Offset must be a multiple of \r
+  NvRamAccessSize , and it must have a value between zero and NvRamSize. \r
+  BufferSize specifies the length of the read or write operation. BufferSize must\r
+  also be a multiple of NvRamAccessSize, and Offset + BufferSize must not exceed\r
+  NvRamSize. \r
+  If any of the above conditions is not met, then EFI_INVALID_PARAMETER will be \r
+  returned. \r
+  If all the conditions are met and the operation is "read," the NVRAM device \r
+  attached to the network interface will be read into Buffer and EFI_SUCCESS \r
+  will be returned. If this is a write operation, the contents of Buffer will be\r
+  used to update the contents of the NVRAM device attached to the network \r
+  interface and EFI_SUCCESS will be returned.\r
+  \r
   It does the basic checking on the input parameters and retrieves snp structure\r
   and then calls the read_nvdata() call which does the actual reading\r
 \r
-  @param  this         context pointer\r
-  @param  ReadOrWrite  true for reading and false for writing\r
-  @param  RegOffset    eeprom register relative to the base\r
-  @param  NumBytes     how many bytes to read\r
-  @param  BufferPtr    address of memory to read into\r
-\r
+  @param This       A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.\r
+  @param ReadWrite  TRUE for read operations, FALSE for write operations.\r
+  @param Offset     Byte offset in the NVRAM device at which to start the read or \r
+                    write operation. This must be a multiple of NvRamAccessSize \r
+                    and less than NvRamSize. (See EFI_SIMPLE_NETWORK_MODE)  \r
+  @param BufferSize The number of bytes to read or write from the NVRAM device. \r
+                    This must also be a multiple of NvramAccessSize.\r
+  @param Buffer     A pointer to the data buffer.\r
+\r
+  @retval EFI_SUCCESS           The NVRAM access was performed.\r
+  @retval EFI_NOT_STARTED       The network interface has not been started.\r
+  @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+                                * The This parameter is NULL \r
+                                * The This parameter does not point to a valid \r
+                                  EFI_SIMPLE_NETWORK_PROTOCOL  structure\r
+                                * The Offset parameter is not a multiple of \r
+                                  EFI_SIMPLE_NETWORK_MODE.NvRamAccessSize\r
+                                * The Offset parameter is not less than \r
+                                  EFI_SIMPLE_NETWORK_MODE.NvRamSize\r
+                                * The BufferSize parameter is not a multiple of \r
+                                  EFI_SIMPLE_NETWORK_MODE.NvRamAccessSize\r
+                                * The Buffer parameter is NULL\r
+  @retval EFI_DEVICE_ERROR      The command could not be sent to the network \r
+                                interface.\r
+  @retval EFI_UNSUPPORTED       This function is not supported by the network\r
+                                interface.\r
 \r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
-snp_undi32_nvdata (\r
-  IN EFI_SIMPLE_NETWORK_PROTOCOL *this,\r
-  IN BOOLEAN                     ReadOrWrite,\r
-  IN UINTN                       RegOffset,\r
-  IN UINTN                       NumBytes,\r
-  IN OUT VOID                    *BufferPtr\r
+SnpUndi32NvData (\r
+  IN EFI_SIMPLE_NETWORK_PROTOCOL *This,\r
+  IN BOOLEAN                     ReadWrite,\r
+  IN UINTN                       Offset,\r
+  IN UINTN                       BufferSize,\r
+  IN OUT VOID                    *Buffer\r
   )\r
 {\r
-  SNP_DRIVER  *snp;\r
+  SNP_DRIVER  *Snp;\r
   EFI_TPL     OldTpl;\r
   EFI_STATUS  Status;\r
 \r
   //\r
   // Get pointer to SNP driver instance for *this.\r
   //\r
-  if (this == NULL) {\r
+  if (This == 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
   //\r
   // Return error if the SNP is not initialized.\r
   //\r
-  switch (snp->mode.State) {\r
+  switch (Snp->Mode.State) {\r
   case EfiSimpleNetworkInitialized:\r
     break;\r
 \r
@@ -152,19 +184,19 @@ snp_undi32_nvdata (
   //\r
   // Return error if non-volatile memory variables are not valid.\r
   //\r
-  if (snp->mode.NvRamSize == 0 || snp->mode.NvRamAccessSize == 0) {\r
+  if (Snp->Mode.NvRamSize == 0 || Snp->Mode.NvRamAccessSize == 0) {\r
     Status = EFI_UNSUPPORTED;\r
     goto ON_EXIT;\r
   }\r
   //\r
   // Check for invalid parameter combinations.\r
   //\r
-  if ((NumBytes == 0) ||\r
-      (BufferPtr == NULL) ||\r
-      (RegOffset >= snp->mode.NvRamSize) ||\r
-      (RegOffset + NumBytes > snp->mode.NvRamSize) ||\r
-      (NumBytes % snp->mode.NvRamAccessSize != 0) ||\r
-      (RegOffset % snp->mode.NvRamAccessSize != 0)\r
+  if ((BufferSize == 0) ||\r
+      (Buffer == NULL) ||\r
+      (Offset >= Snp->Mode.NvRamSize) ||\r
+      (Offset + BufferSize > Snp->Mode.NvRamSize) ||\r
+      (BufferSize % Snp->Mode.NvRamAccessSize != 0) ||\r
+      (Offset % Snp->Mode.NvRamAccessSize != 0)\r
       ) {\r
     Status = EFI_INVALID_PARAMETER;\r
     goto ON_EXIT;\r
@@ -172,10 +204,10 @@ snp_undi32_nvdata (
   //\r
   // check the implementation flags of undi if we can write the nvdata!\r
   //\r
-  if (!ReadOrWrite) {\r
+  if (!ReadWrite) {\r
     Status = EFI_UNSUPPORTED;\r
   } else {\r
-    Status = pxe_nvdata_read (snp, RegOffset, NumBytes, BufferPtr);\r
+    Status = PxeNvDataRead (Snp, Offset, BufferSize, Buffer);\r
   }\r
 \r
 ON_EXIT:\r