public inbox for devel@edk2.groups.io
 help / color / mirror / Atom feed
From: "Nhi Pham" <nhi@os.amperecomputing.com>
To: devel@edk2.groups.io
Cc: Nhi Pham <nhi@os.amperecomputing.com>,
	Leif Lindholm <leif@nuviainc.com>,
	Ard Biesheuvel <ard.biesheuvel@arm.com>
Subject: [PATCH v2 1/4] EmbeddedPkg/TimeBaseLib: Update comment blocks for API functions
Date: Wed,  6 Jan 2021 23:09:00 +0700	[thread overview]
Message-ID: <20210106160903.27679-2-nhi@os.amperecomputing.com> (raw)
In-Reply-To: <20210106160903.27679-1-nhi@os.amperecomputing.com>

This updates Doxygen comment blocks for API library functions.

Cc: Leif Lindholm <leif@nuviainc.com>
Cc: Ard Biesheuvel <ard.biesheuvel@arm.com>
Signed-off-by: Nhi Pham <nhi@os.amperecomputing.com>
---
 EmbeddedPkg/Include/Library/TimeBaseLib.h     | 54 +++++++++++++++--
 EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c | 64 +++++++++++++++++---
 2 files changed, 104 insertions(+), 14 deletions(-)

diff --git a/EmbeddedPkg/Include/Library/TimeBaseLib.h b/EmbeddedPkg/Include/Library/TimeBaseLib.h
index 90853c3f4b93..a9f3c6588b75 100644
--- a/EmbeddedPkg/Include/Library/TimeBaseLib.h
+++ b/EmbeddedPkg/Include/Library/TimeBaseLib.h
@@ -2,6 +2,7 @@
 *
 *  Copyright (c) 2016, Hisilicon Limited. All rights reserved.
 *  Copyright (c) 2016-2019, Linaro Limited. All rights reserved.
+*  Copyright (c) 2021, Ampere Computing LLC. All rights reserved.
 *
 *  SPDX-License-Identifier: BSD-2-Clause-Patent
 *
@@ -52,18 +53,45 @@
 #define SEC_PER_HOUR                                    ((UINTN)  3600)
 #define SEC_PER_DAY                                     ((UINTN) 86400)
 
+/**
+  Check if it is a leap year.
+
+  @param    Time  The UEFI time to be checked.
+
+  @retval   TRUE  It is a leap year.
+  @retval   FALSE It is NOT a leap year.
+
+**/
 BOOLEAN
 EFIAPI
 IsLeapYear (
   IN  EFI_TIME  *Time
   );
 
+/**
+  Check if the day in the UEFI time is valid.
+
+  @param    Time    The UEFI time to be checked.
+
+  @retval   TRUE    Valid.
+  @retval   FALSE   Invalid.
+
+**/
 BOOLEAN
 EFIAPI
 IsDayValid (
   IN  EFI_TIME  *Time
   );
 
+/**
+  Check if the UEFI time is valid.
+
+  @param    Time    The UEFI time to be checked.
+
+  @retval   TRUE    Valid.
+  @retval   FALSE   Invalid.
+
+**/
 BOOLEAN
 EFIAPI
 IsTimeValid (
@@ -71,8 +99,12 @@ IsTimeValid (
   );
 
 /**
-  Converts Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC) to EFI_TIME
- **/
+  Converts Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC) to EFI_TIME.
+
+  @param  EpochSeconds   Epoch seconds.
+  @param  Time           The time converted to UEFI format.
+
+**/
 VOID
 EFIAPI
 EpochToEfiTime (
@@ -81,8 +113,13 @@ EpochToEfiTime (
   );
 
 /**
-  Converts EFI_TIME to Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC)
- **/
+  Converts EFI_TIME to Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC).
+
+  @param    Time  The UEFI time to be converted.
+
+  @return   Number of seconds.
+
+**/
 UINTN
 EFIAPI
 EfiTimeToEpoch (
@@ -90,8 +127,13 @@ EfiTimeToEpoch (
   );
 
 /**
-  returns Day of the week [0-6] 0=Sunday
- **/
+  Get the day of the week from the UEFI time.
+
+  @param    Time  The UEFI time to be calculated.
+
+  @return   The day of the week: Sunday=0, Monday=1, ... Saturday=6
+
+**/
 UINTN
 EfiTimeToWday (
   IN  EFI_TIME  *Time
diff --git a/EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c b/EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c
index 78fc7b6cd2e5..c9048d765960 100644
--- a/EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c
+++ b/EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c
@@ -2,6 +2,7 @@
 *
 *  Copyright (c) 2016, Hisilicon Limited. All rights reserved.
 *  Copyright (c) 2016-2019, Linaro Limited. All rights reserved.
+*  Copyright (c) 2021, Ampere Computing LLC. All rights reserved.
 *
 *  SPDX-License-Identifier: BSD-2-Clause-Patent
 *
@@ -13,8 +14,12 @@
 #include <Library/TimeBaseLib.h>
 
 /**
-  Converts Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC) to EFI_TIME
- **/
+  Converts Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC) to EFI_TIME.
+
+  @param  EpochSeconds   Epoch seconds.
+  @param  Time           The time converted to UEFI format.
+
+**/
 VOID
 EFIAPI
 EpochToEfiTime (
@@ -71,8 +76,13 @@ EpochToEfiTime (
 }
 
 /**
-  Calculate Epoch days
- **/
+  Calculate Epoch days.
+
+  @param    Time  The UEFI time to be calculated.
+
+  @return   Number of days.
+
+**/
 UINTN
 EFIAPI
 EfiGetEpochDays (
@@ -96,9 +106,15 @@ EfiGetEpochDays (
 
   return EpochDays;
 }
+
 /**
-  Converts EFI_TIME to Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC)
- **/
+  Converts EFI_TIME to Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC).
+
+  @param    Time  The UEFI time to be converted.
+
+  @return   Number of seconds.
+
+**/
 UINTN
 EFIAPI
 EfiTimeToEpoch (
@@ -116,8 +132,13 @@ EfiTimeToEpoch (
 }
 
 /**
-  returns Day of the week [0-6] 0=Sunday
- **/
+  Get the day of the week from the UEFI time.
+
+  @param    Time  The UEFI time to be calculated.
+
+  @return   The day of the week: Sunday=0, Monday=1, ... Saturday=6
+
+**/
 UINTN
 EfiTimeToWday (
   IN  EFI_TIME  *Time
@@ -132,6 +153,15 @@ EfiTimeToWday (
   return (EpochDays + 4) % 7;
 }
 
+/**
+  Check if it is a leap year.
+
+  @param    Time  The UEFI time to be checked.
+
+  @retval   TRUE  It is a leap year.
+  @retval   FALSE It is NOT a leap year.
+
+**/
 BOOLEAN
 EFIAPI
 IsLeapYear (
@@ -153,6 +183,15 @@ IsLeapYear (
   }
 }
 
+/**
+  Check if the day in the UEFI time is valid.
+
+  @param    Time    The UEFI time to be checked.
+
+  @retval   TRUE    Valid.
+  @retval   FALSE   Invalid.
+
+**/
 BOOLEAN
 EFIAPI
 IsDayValid (
@@ -171,6 +210,15 @@ IsDayValid (
   return TRUE;
 }
 
+/**
+  Check if the UEFI time is valid.
+
+  @param    Time    The UEFI time to be checked.
+
+  @retval   TRUE    Valid.
+  @retval   FALSE   Invalid.
+
+**/
 BOOLEAN
 EFIAPI
 IsTimeValid(
-- 
2.17.1


  reply	other threads:[~2021-01-06 16:09 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-01-06 16:08 [PATCH v2 0/4] EmbeddedPkg/TimeBaseLib: Reduce duplicate code in RTC modules Nhi Pham
2021-01-06 16:09 ` Nhi Pham [this message]
2021-01-06 16:09 ` [PATCH v2 2/4] EmbeddedPkg/TimeBaseLib: Fix for minor code formatting Nhi Pham
2021-01-06 16:09 ` [PATCH v2 3/4] EmbeddedPkg/TimeBaseLib: Add function to check Timezone and Daylight Nhi Pham
2021-01-06 16:09 ` [PATCH v2 4/4] EmbeddedPkg/RealTimeClockRuntimeDxe: Use helper functions from TimeBaseLib Nhi Pham
2021-01-07 17:42 ` [PATCH v2 0/4] EmbeddedPkg/TimeBaseLib: Reduce duplicate code in RTC modules Leif Lindholm

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-list from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210106160903.27679-2-nhi@os.amperecomputing.com \
    --to=devel@edk2.groups.io \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox