Add doxygen style comments for functions in DxeMain.

[mirror_edk2.git] / MdeModulePkg / Core / Dxe / FwVol / Ffs.c

diff --git a/MdeModulePkg/Core/Dxe/FwVol/Ffs.c b/MdeModulePkg/Core/Dxe/FwVol/Ffs.c
index 23c84b34f8e6a3f38e2d525cd4e3a157a1469781..736e840cb70e5a2eeb78a0dcd13906230a0c3e94 100644 (file)
--- a/MdeModulePkg/Core/Dxe/FwVol/Ffs.c
+++ b/MdeModulePkg/Core/Dxe/FwVol/Ffs.c
@@ -1,6 +1,8 @@
-/*++\r
+/** @file \r
 \r
-Copyright (c) 2006, Intel Corporation                                                         \r
+  FFS file access utilities.\r
+\r
+Copyright (c) 2006 - 2008, 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
@@ -9,40 +11,28 @@ http://opensource.org/licenses/bsd-license.php
 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
+**/\r
 \r
-  Ffs.c\r
 \r
-Abstract:\r
-\r
-  FFS file access utilities.\r
+#include <DxeMain.h>\r
 \r
---*/\r
+#define PHYSICAL_ADDRESS_TO_POINTER(Address) ((VOID *)((UINTN)(Address)))\r
 \r
 \r
-#include <DxeMain.h>\r
+/**\r
+  Get the FFS file state by checking the highest bit set in the header's state field.\r
 \r
-#define PHYSICAL_ADDRESS_TO_POINTER(Address) ((VOID *)((UINTN)(Address)))\r
+  @param  ErasePolarity  Erase polarity attribute of the firmware volume \r
+  @param  FfsHeader      Points to the FFS file header \r
 \r
+  @return FFS File state\r
 \r
+**/\r
 EFI_FFS_FILE_STATE\r
 GetFileState (\r
   IN UINT8                ErasePolarity,\r
   IN EFI_FFS_FILE_HEADER  *FfsHeader\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  Get the FFS file state by checking the highest bit set in the header's state field\r
-\r
-Arguments:\r
-  ErasePolarity -  Erase polarity attribute of the firmware volume\r
-  FfsHeader     -  Points to the FFS file header\r
-    \r
-Returns:\r
-  FFS File state \r
-    \r
---*/\r
 {\r
   EFI_FFS_FILE_STATE      FileState;\r
   UINT8                   HighestBit;\r
@@ -62,27 +52,24 @@ Returns:
 }\r
 \r
 \r
+\r
+/**\r
+  Check if a block of buffer is erased.\r
+\r
+  @param  ErasePolarity  Erase polarity attribute of the firmware volume \r
+  @param  InBuffer       The buffer to be checked \r
+  @param  BufferSize     Size of the buffer in bytes \r
+\r
+  @retval TRUE           The block of buffer is erased \r
+  @retval FALSE          The block of buffer is not erased\r
+\r
+**/\r
 BOOLEAN\r
 IsBufferErased (\r
   IN UINT8    ErasePolarity,\r
   IN VOID     *InBuffer,\r
   IN UINTN    BufferSize\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  Check if a block of buffer is erased\r
-\r
-Arguments:\r
-  ErasePolarity -  Erase polarity attribute of the firmware volume\r
-  InBuffer      -  The buffer to be checked\r
-  BufferSize    -  Size of the buffer in bytes\r
-    \r
-Returns:\r
-  TRUE  -  The block of buffer is erased\r
-  FALSE -  The block of buffer is not erased\r
-    \r
---*/\r
 {\r
   UINTN   Count;\r
   UINT8   EraseByte;\r
@@ -105,35 +92,32 @@ Returns:
 }\r
 \r
 \r
+\r
+/**\r
+  Verify checksum of the firmware volume header.\r
+\r
+  @param  FvHeader       Points to the firmware volume header to be checked \r
+\r
+  @retval TRUE           Checksum verification passed \r
+  @retval FALSE          Checksum verification failed\r
+\r
+**/\r
 BOOLEAN\r
 VerifyFvHeaderChecksum (\r
   IN EFI_FIRMWARE_VOLUME_HEADER *FvHeader\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  Verify checksum of the firmware volume header \r
-\r
-Arguments:\r
-  FvHeader  -  Points to the firmware volume header to be checked\r
-    \r
-Returns:\r
-  TRUE  -  Checksum verification passed\r
-  FALSE -  Checksum verification failed\r
-    \r
---*/\r
 {\r
   UINT32  Index;\r
   UINT32  HeaderLength;\r
   UINT16  Checksum;\r
-  UINT16  *ptr;\r
+  UINT16  *Ptr;\r
 \r
   HeaderLength = FvHeader->HeaderLength;\r
-  ptr = (UINT16 *)FvHeader;\r
+  Ptr = (UINT16 *)FvHeader;\r
   Checksum = 0;\r
 \r
   for (Index = 0; Index < HeaderLength / sizeof (UINT16); Index++) {\r
-    Checksum = (UINT16)(Checksum + ptr[Index]);\r
+    Checksum = (UINT16)(Checksum + Ptr[Index]);\r
   }\r
 \r
   if (Checksum == 0) {\r
@@ -143,33 +127,30 @@ Returns:
   }\r
 }\r
 \r
+\r
+/**\r
+  Verify checksum of the FFS file header.\r
+\r
+  @param  FfsHeader      Points to the FFS file header to be checked \r
+\r
+  @retval TRUE           Checksum verification passed \r
+  @retval FALSE          Checksum verification failed\r
+\r
+**/\r
 STATIC\r
 BOOLEAN\r
 VerifyHeaderChecksum (\r
   IN EFI_FFS_FILE_HEADER  *FfsHeader\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  Verify checksum of the FFS file header \r
-\r
-Arguments:\r
-  FfsHeader  -  Points to the FFS file header to be checked\r
-    \r
-Returns:\r
-  TRUE  -  Checksum verification passed\r
-  FALSE -  Checksum verification failed\r
-    \r
---*/\r
 {\r
   UINT32            Index;\r
-  UINT8             *ptr;\r
+  UINT8             *Ptr;\r
   UINT8             HeaderChecksum;\r
 \r
-  ptr = (UINT8 *)FfsHeader;\r
+  Ptr = (UINT8 *)FfsHeader;\r
   HeaderChecksum = 0;\r
   for (Index = 0; Index < sizeof(EFI_FFS_FILE_HEADER); Index++) {\r
-    HeaderChecksum = (UINT8)(HeaderChecksum + ptr[Index]);\r
+    HeaderChecksum = (UINT8)(HeaderChecksum + Ptr[Index]);\r
   }\r
 \r
   HeaderChecksum = (UINT8) (HeaderChecksum - FfsHeader->State - FfsHeader->IntegrityCheck.Checksum.File);\r
@@ -182,27 +163,24 @@ Returns:
 }\r
 \r
 \r
+\r
+/**\r
+  Check if it's a valid FFS file header.\r
+\r
+  @param  ErasePolarity  Erase polarity attribute of the firmware volume \r
+  @param  FfsHeader      Points to the FFS file header to be checked \r
+  @param  FileState      FFS file state to be returned \r
+\r
+  @retval TRUE           Valid FFS file header \r
+  @retval FALSE          Invalid FFS file header\r
+\r
+**/\r
 BOOLEAN\r
 IsValidFfsHeader (\r
   IN UINT8                ErasePolarity,\r
   IN EFI_FFS_FILE_HEADER  *FfsHeader,\r
   OUT EFI_FFS_FILE_STATE  *FileState\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  Check if it's a valid FFS file header\r
-\r
-Arguments:\r
-  ErasePolarity -  Erase polarity attribute of the firmware volume\r
-  FfsHeader     -  Points to the FFS file header to be checked\r
-  FileState     -  FFS file state to be returned\r
-    \r
-Returns:\r
-  TRUE  -  Valid FFS file header\r
-  FALSE -  Invalid FFS file header\r
-    \r
---*/\r
 {\r
   *FileState = GetFileState (ErasePolarity, FfsHeader);\r
 \r
@@ -224,26 +202,23 @@ Returns:
 }\r
 \r
 \r
+\r
+/**\r
+  Check if it's a valid FFS file.\r
+  Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.\r
+\r
+  @param  ErasePolarity  Erase polarity attribute of the firmware volume \r
+  @param  FfsHeader      Points to the FFS file to be checked \r
+\r
+  @retval TRUE           Valid FFS file \r
+  @retval FALSE          Invalid FFS file\r
+\r
+**/\r
 BOOLEAN\r
 IsValidFfsFile (\r
   IN UINT8                ErasePolarity,\r
   IN EFI_FFS_FILE_HEADER  *FfsHeader\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  Check if it's a valid FFS file. \r
-  Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.\r
-\r
-Arguments:\r
-  ErasePolarity -  Erase polarity attribute of the firmware volume\r
-  FfsHeader     -  Points to the FFS file to be checked\r
-    \r
-Returns:\r
-  TRUE  -  Valid FFS file\r
-  FALSE -  Invalid FFS file\r
-    \r
---*/\r
 {\r
   EFI_FFS_FILE_STATE  FileState;\r
 \r
@@ -264,3 +239,4 @@ Returns:
   }\r
 }\r
 \r
+\r