EmbeddedPkg/TimeBaseLib: Update comment blocks for API functions

[mirror_edk2.git] / EmbeddedPkg / Library / TimeBaseLib / TimeBaseLib.c

diff --git a/EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c b/EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c
index 662cbdd5da99c32d4d613ae67fcc72d14c05cdc0..c9048d76596087802655a430d0b892953cc40816 100644 (file)
--- a/EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c
+++ b/EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c
@@ -1,7 +1,8 @@
 /** @file\r
 *\r
 *  Copyright (c) 2016, Hisilicon Limited. All rights reserved.\r
-*  Copyright (c) 2016, Linaro Limited. All rights reserved.\r
+*  Copyright (c) 2016-2019, Linaro Limited. All rights reserved.\r
+*  Copyright (c) 2021, Ampere Computing LLC. All rights reserved.\r
 *\r
 *  SPDX-License-Identifier: BSD-2-Clause-Patent\r
 *\r
@@ -13,8 +14,12 @@
 #include <Library/TimeBaseLib.h>\r
 \r
 /**\r
-  Converts Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC) to EFI_TIME\r
- **/\r
+  Converts Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC) to EFI_TIME.\r
+\r
+  @param  EpochSeconds   Epoch seconds.\r
+  @param  Time           The time converted to UEFI format.\r
+\r
+**/\r
 VOID\r
 EFIAPI\r
 EpochToEfiTime (\r
@@ -53,9 +58,9 @@ EpochToEfiTime (
   m  = (((da * 5) + 308) / 153) - 2;\r
   d  = da - (((m + 4) * 153) / 5) + 122;\r
 \r
-  Time->Year  = y - 4800 + ((m + 2) / 12);\r
+  Time->Year  = (UINT16)(y - 4800 + ((m + 2) / 12));\r
   Time->Month = ((m + 2) % 12) + 1;\r
-  Time->Day   = d + 1;\r
+  Time->Day   = (UINT8)(d + 1);\r
 \r
   ss = EpochSeconds % 60;\r
   a  = (EpochSeconds - ss) / 60;\r
@@ -63,16 +68,21 @@ EpochToEfiTime (
   b = (a - mm) / 60;\r
   hh = b % 24;\r
 \r
-  Time->Hour        = hh;\r
-  Time->Minute      = mm;\r
-  Time->Second      = ss;\r
+  Time->Hour        = (UINT8)hh;\r
+  Time->Minute      = (UINT8)mm;\r
+  Time->Second      = (UINT8)ss;\r
   Time->Nanosecond  = 0;\r
 \r
 }\r
 \r
 /**\r
-  Calculate Epoch days\r
- **/\r
+  Calculate Epoch days.\r
+\r
+  @param    Time  The UEFI time to be calculated.\r
+\r
+  @return   Number of days.\r
+\r
+**/\r
 UINTN\r
 EFIAPI\r
 EfiGetEpochDays (\r
@@ -96,9 +106,15 @@ EfiGetEpochDays (
 \r
   return EpochDays;\r
 }\r
+\r
 /**\r
-  Converts EFI_TIME to Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC)\r
- **/\r
+  Converts EFI_TIME to Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC).\r
+\r
+  @param    Time  The UEFI time to be converted.\r
+\r
+  @return   Number of seconds.\r
+\r
+**/\r
 UINTN\r
 EFIAPI\r
 EfiTimeToEpoch (\r
@@ -116,8 +132,13 @@ EfiTimeToEpoch (
 }\r
 \r
 /**\r
-  returns Day of the week [0-6] 0=Sunday\r
- **/\r
+  Get the day of the week from the UEFI time.\r
+\r
+  @param    Time  The UEFI time to be calculated.\r
+\r
+  @return   The day of the week: Sunday=0, Monday=1, ... Saturday=6\r
+\r
+**/\r
 UINTN\r
 EfiTimeToWday (\r
   IN  EFI_TIME  *Time\r
@@ -132,6 +153,15 @@ EfiTimeToWday (
   return (EpochDays + 4) % 7;\r
 }\r
 \r
+/**\r
+  Check if it is a leap year.\r
+\r
+  @param    Time  The UEFI time to be checked.\r
+\r
+  @retval   TRUE  It is a leap year.\r
+  @retval   FALSE It is NOT a leap year.\r
+\r
+**/\r
 BOOLEAN\r
 EFIAPI\r
 IsLeapYear (\r
@@ -153,6 +183,15 @@ IsLeapYear (
   }\r
 }\r
 \r
+/**\r
+  Check if the day in the UEFI time is valid.\r
+\r
+  @param    Time    The UEFI time to be checked.\r
+\r
+  @retval   TRUE    Valid.\r
+  @retval   FALSE   Invalid.\r
+\r
+**/\r
 BOOLEAN\r
 EFIAPI\r
 IsDayValid (\r
@@ -171,6 +210,15 @@ IsDayValid (
   return TRUE;\r
 }\r
 \r
+/**\r
+  Check if the UEFI time is valid.\r
+\r
+  @param    Time    The UEFI time to be checked.\r
+\r
+  @retval   TRUE    Valid.\r
+  @retval   FALSE   Invalid.\r
+\r
+**/\r
 BOOLEAN\r
 EFIAPI\r
 IsTimeValid(\r