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 b62fab9cd942702f3e170fef34d2abf6f3a3d506..736e840cb70e5a2eeb78a0dcd13906230a0c3e94 100644 (file)
--- a/MdeModulePkg/Core/Dxe/FwVol/Ffs.c
+++ b/MdeModulePkg/Core/Dxe/FwVol/Ffs.c
@@ -19,24 +19,20 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #define PHYSICAL_ADDRESS_TO_POINTER(Address) ((VOID *)((UINTN)(Address)))\r
 \r
 \r
+/**\r
+  Get the FFS file state by checking the highest bit set in the header's state field.\r
+\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
@@ -56,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
@@ -99,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
@@ -137,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
@@ -176,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
@@ -218,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
@@ -258,3 +239,4 @@ Returns:
   }\r
 }\r
 \r
+\r