EmbeddedPkg/TimeBaseLib: Update comment blocks for API functions

[mirror_edk2.git] / EmbeddedPkg / Include / Library / TimeBaseLib.h

/** @file\r
*\r
*  Copyright (c) 2016, Hisilicon 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
**/\r
\r
#ifndef _TIME_BASE_LIB_H_\r
#define _TIME_BASE_LIB_H_\r
\r
#include <Uefi/UefiBaseType.h>\r
\r
//\r
// Convenience macros to obtain a build date\r
//\r
// These macros should work for any compiler that follows ISO/IEC 9899,\r
// in which case __DATE__ is defined as a "Mmm dd yyyy" 11 chars string,\r
// but add an explicit filter for compilers that have been validated.\r
//\r
#if (defined(__GNUC__) || defined(_MSC_VER) || defined(__clang__))\r
#define TIME_BUILD_YEAR  (__DATE__[7] == '?' ? 1900 \\r
          : (((__DATE__[7] - '0') * 1000 )          \\r
          + (__DATE__[8] - '0') * 100               \\r
          + (__DATE__[9] - '0') * 10                \\r
          + __DATE__[10] - '0'))\r
#define TIME_BUILD_MONTH ( __DATE__ [2] == '?' ? 1  \\r
          : __DATE__ [2] == 'n' ? (                 \\r
            __DATE__ [1] == 'a' ? 1 : 6)            \\r
          : __DATE__ [2] == 'b' ? 2                 \\r
          : __DATE__ [2] == 'r' ? (                 \\r
            __DATE__ [0] == 'M' ? 3 : 4)            \\r
          : __DATE__ [2] == 'y' ? 5                 \\r
          : __DATE__ [2] == 'l' ? 7                 \\r
          : __DATE__ [2] == 'g' ? 8                 \\r
          : __DATE__ [2] == 'p' ? 9                 \\r
          : __DATE__ [2] == 't' ? 10                \\r
          : __DATE__ [2] == 'v' ? 11                \\r
          : 12)\r
#define TIME_BUILD_DAY ( __DATE__[4] == '?' ? 1     \\r
          : ((__DATE__[4] == ' ' ? 0 :              \\r
            ((__DATE__[4] - '0') * 10))             \\r
          + __DATE__[5] - '0'))\r
#endif\r
\r
// Define EPOCH (1970-JANUARY-01) in the Julian Date representation\r
#define EPOCH_JULIAN_DATE                               2440588\r
\r
// Seconds per unit\r
#define SEC_PER_MIN                                     ((UINTN)    60)\r
#define SEC_PER_HOUR                                    ((UINTN)  3600)\r
#define SEC_PER_DAY                                     ((UINTN) 86400)\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
  IN  EFI_TIME  *Time\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
  IN  EFI_TIME  *Time\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
  IN  EFI_TIME  *Time\r
  );\r
\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
  IN  UINTN     EpochSeconds,\r
  OUT EFI_TIME  *Time\r
  );\r
\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
  IN  EFI_TIME  *Time\r
  );\r
\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
  );\r
\r
#endif\r