PcAtChipsetPkg/PcatRealTimeClockRuntimeDxe/PcRtc.h

   1 /** @file
   2   Header file for real time clock driver.
   3
   4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5 Copyright (c) 2017, AMD Inc. All rights reserved.<BR>
   6
   7 SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef _RTC_H_
  12 #define _RTC_H_
  13
  14 #include <Uefi.h>
  15
  16 #include <Guid/Acpi.h>
  17
  18 #include <Protocol/RealTimeClock.h>
  19
  20 #include <Library/BaseLib.h>
  21 #include <Library/DebugLib.h>
  22 #include <Library/UefiLib.h>
  23 #include <Library/BaseMemoryLib.h>
  24 #include <Library/IoLib.h>
  25 #include <Library/TimerLib.h>
  26 #include <Library/UefiDriverEntryPoint.h>
  27 #include <Library/UefiBootServicesTableLib.h>
  28 #include <Library/UefiRuntimeLib.h>
  29 #include <Library/UefiRuntimeServicesTableLib.h>
  30 #include <Library/PcdLib.h>
  31 #include <Library/ReportStatusCodeLib.h>
  32
  33 typedef struct {
  34   EFI_LOCK    RtcLock;
  35   INT16       SavedTimeZone;
  36   UINT8       Daylight;
  37   UINT8       CenturyRtcAddress;
  38 } PC_RTC_MODULE_GLOBALS;
  39
  40 extern PC_RTC_MODULE_GLOBALS  mModuleGlobal;
  41
  42 //
  43 // Dallas DS12C887 Real Time Clock
  44 //
  45 #define RTC_ADDRESS_SECONDS           0   // R/W  Range 0..59
  46 #define RTC_ADDRESS_SECONDS_ALARM     1   // R/W  Range 0..59
  47 #define RTC_ADDRESS_MINUTES           2   // R/W  Range 0..59
  48 #define RTC_ADDRESS_MINUTES_ALARM     3   // R/W  Range 0..59
  49 #define RTC_ADDRESS_HOURS             4   // R/W  Range 1..12 or 0..23 Bit 7 is AM/PM
  50 #define RTC_ADDRESS_HOURS_ALARM       5   // R/W  Range 1..12 or 0..23 Bit 7 is AM/PM
  51 #define RTC_ADDRESS_DAY_OF_THE_WEEK   6   // R/W  Range 1..7
  52 #define RTC_ADDRESS_DAY_OF_THE_MONTH  7   // R/W  Range 1..31
  53 #define RTC_ADDRESS_MONTH             8   // R/W  Range 1..12
  54 #define RTC_ADDRESS_YEAR              9   // R/W  Range 0..99
  55 #define RTC_ADDRESS_REGISTER_A        10  // R/W[0..6]  R0[7]
  56 #define RTC_ADDRESS_REGISTER_B        11  // R/W
  57 #define RTC_ADDRESS_REGISTER_C        12  // RO
  58 #define RTC_ADDRESS_REGISTER_D        13  // RO
  59 //
  60 // Date and time initial values.
  61 // They are used if the RTC values are invalid during driver initialization
  62 //
  63 #define RTC_INIT_SECOND  0
  64 #define RTC_INIT_MINUTE  0
  65 #define RTC_INIT_HOUR    0
  66 #define RTC_INIT_DAY     1
  67 #define RTC_INIT_MONTH   1
  68
  69 #pragma pack(1)
  70 //
  71 // Register A
  72 //
  73 typedef struct {
  74   UINT8    Rs  : 4; // Rate Selection Bits
  75   UINT8    Dv  : 3; // Divisor
  76   UINT8    Uip : 1; // Update in progress
  77 } RTC_REGISTER_A_BITS;
  78
  79 typedef union {
  80   RTC_REGISTER_A_BITS    Bits;
  81   UINT8                  Data;
  82 } RTC_REGISTER_A;
  83
  84 //
  85 // Register B
  86 //
  87 typedef struct {
  88   UINT8    Dse  : 1; // 0 - Daylight saving disabled  1 - Daylight savings enabled
  89   UINT8    Mil  : 1; // 0 - 12 hour mode              1 - 24 hour mode
  90   UINT8    Dm   : 1; // 0 - BCD Format                1 - Binary Format
  91   UINT8    Sqwe : 1; // 0 - Disable SQWE output       1 - Enable SQWE output
  92   UINT8    Uie  : 1; // 0 - Update INT disabled       1 - Update INT enabled
  93   UINT8    Aie  : 1; // 0 - Alarm INT disabled        1 - Alarm INT Enabled
  94   UINT8    Pie  : 1; // 0 - Periodic INT disabled     1 - Periodic INT Enabled
  95   UINT8    Set  : 1; // 0 - Normal operation.         1 - Updates inhibited
  96 } RTC_REGISTER_B_BITS;
  97
  98 typedef union {
  99   RTC_REGISTER_B_BITS    Bits;
 100   UINT8                  Data;
 101 } RTC_REGISTER_B;
 102
 103 //
 104 // Register C
 105 //
 106 typedef struct {
 107   UINT8    Reserved : 4; // Read as zero.  Can not be written.
 108   UINT8    Uf       : 1; // Update End Interrupt Flag
 109   UINT8    Af       : 1; // Alarm Interrupt Flag
 110   UINT8    Pf       : 1; // Periodic Interrupt Flag
 111   UINT8    Irqf     : 1; // Interrupt Request Flag = PF & PIE | AF & AIE | UF & UIE
 112 } RTC_REGISTER_C_BITS;
 113
 114 typedef union {
 115   RTC_REGISTER_C_BITS    Bits;
 116   UINT8                  Data;
 117 } RTC_REGISTER_C;
 118
 119 //
 120 // Register D
 121 //
 122 typedef struct {
 123   UINT8    Reserved : 7; // Read as zero.  Can not be written.
 124   UINT8    Vrt      : 1; // Valid RAM and Time
 125 } RTC_REGISTER_D_BITS;
 126
 127 typedef union {
 128   RTC_REGISTER_D_BITS    Bits;
 129   UINT8                  Data;
 130 } RTC_REGISTER_D;
 131
 132 #pragma pack()
 133
 134 /**
 135   Initialize RTC.
 136
 137   @param  Global            For global use inside this module.
 138
 139   @retval EFI_DEVICE_ERROR  Initialization failed due to device error.
 140   @retval EFI_SUCCESS       Initialization successful.
 141
 142 **/
 143 EFI_STATUS
 144 PcRtcInit (
 145   IN PC_RTC_MODULE_GLOBALS  *Global
 146   );
 147
 148 /**
 149   Sets the current local time and date information.
 150
 151   @param  Time                  A pointer to the current time.
 152   @param  Global                For global use inside this module.
 153
 154   @retval EFI_SUCCESS           The operation completed successfully.
 155   @retval EFI_INVALID_PARAMETER A time field is out of range.
 156   @retval EFI_DEVICE_ERROR      The time could not be set due due to hardware error.
 157
 158 **/
 159 EFI_STATUS
 160 PcRtcSetTime (
 161   IN EFI_TIME               *Time,
 162   IN PC_RTC_MODULE_GLOBALS  *Global
 163   );
 164
 165 /**
 166   Returns the current time and date information, and the time-keeping capabilities
 167   of the hardware platform.
 168
 169   @param  Time          A pointer to storage to receive a snapshot of the current time.
 170   @param  Capabilities  An optional pointer to a buffer to receive the real time clock
 171                         device's capabilities.
 172   @param  Global        For global use inside this module.
 173
 174   @retval EFI_SUCCESS            The operation completed successfully.
 175   @retval EFI_INVALID_PARAMETER  Time is NULL.
 176   @retval EFI_DEVICE_ERROR       The time could not be retrieved due to hardware error.
 177
 178 **/
 179 EFI_STATUS
 180 PcRtcGetTime (
 181   OUT EFI_TIME               *Time,
 182   OUT EFI_TIME_CAPABILITIES  *Capabilities  OPTIONAL,
 183   IN  PC_RTC_MODULE_GLOBALS  *Global
 184   );
 185
 186 /**
 187   Sets the system wakeup alarm clock time.
 188
 189   @param  Enabled  Enable or disable the wakeup alarm.
 190   @param  Time     If Enable is TRUE, the time to set the wakeup alarm for.
 191                    If Enable is FALSE, then this parameter is optional, and may be NULL.
 192   @param  Global   For global use inside this module.
 193
 194   @retval EFI_SUCCESS           If Enable is TRUE, then the wakeup alarm was enabled.
 195                                 If Enable is FALSE, then the wakeup alarm was disabled.
 196   @retval EFI_INVALID_PARAMETER A time field is out of range.
 197   @retval EFI_DEVICE_ERROR      The wakeup time could not be set due to a hardware error.
 198   @retval EFI_UNSUPPORTED       A wakeup timer is not supported on this platform.
 199
 200 **/
 201 EFI_STATUS
 202 PcRtcSetWakeupTime (
 203   IN BOOLEAN                Enable,
 204   IN EFI_TIME               *Time   OPTIONAL,
 205   IN PC_RTC_MODULE_GLOBALS  *Global
 206   );
 207
 208 /**
 209   Returns the current wakeup alarm clock setting.
 210
 211   @param  Enabled  Indicates if the alarm is currently enabled or disabled.
 212   @param  Pending  Indicates if the alarm signal is pending and requires acknowledgement.
 213   @param  Time     The current alarm setting.
 214   @param  Global   For global use inside this module.
 215
 216   @retval EFI_SUCCESS           The alarm settings were returned.
 217   @retval EFI_INVALID_PARAMETER Enabled is NULL.
 218   @retval EFI_INVALID_PARAMETER Pending is NULL.
 219   @retval EFI_INVALID_PARAMETER Time is NULL.
 220   @retval EFI_DEVICE_ERROR      The wakeup time could not be retrieved due to a hardware error.
 221   @retval EFI_UNSUPPORTED       A wakeup timer is not supported on this platform.
 222
 223 **/
 224 EFI_STATUS
 225 PcRtcGetWakeupTime (
 226   OUT BOOLEAN                *Enabled,
 227   OUT BOOLEAN                *Pending,
 228   OUT EFI_TIME               *Time,
 229   IN  PC_RTC_MODULE_GLOBALS  *Global
 230   );
 231
 232 /**
 233   The user Entry Point for PcRTC module.
 234
 235   This is the entry point for PcRTC module. It installs the UEFI runtime service
 236   including GetTime(),SetTime(),GetWakeupTime(),and SetWakeupTime().
 237
 238   @param  ImageHandle    The firmware allocated handle for the EFI image.
 239   @param  SystemTable    A pointer to the EFI System Table.
 240
 241   @retval EFI_SUCCESS    The entry point is executed successfully.
 242   @retval Others         Some error occurs when executing this entry point.
 243
 244 **/
 245 EFI_STATUS
 246 EFIAPI
 247 InitializePcRtc (
 248   IN EFI_HANDLE        ImageHandle,
 249   IN EFI_SYSTEM_TABLE  *SystemTable
 250   );
 251
 252 /**
 253   See if all fields of a variable of EFI_TIME type is correct.
 254
 255   @param   Time   The time to be checked.
 256
 257   @retval  EFI_INVALID_PARAMETER  Some fields of Time are not correct.
 258   @retval  EFI_SUCCESS            Time is a valid EFI_TIME variable.
 259
 260 **/
 261 EFI_STATUS
 262 RtcTimeFieldsValid (
 263   IN EFI_TIME  *Time
 264   );
 265
 266 /**
 267   Converts time from EFI_TIME format defined by UEFI spec to RTC format.
 268
 269   This function converts time from EFI_TIME format defined by UEFI spec to RTC format.
 270   If data mode of RTC is BCD, then converts EFI_TIME to it.
 271   If RTC is in 12-hour format, then converts EFI_TIME to it.
 272
 273   @param   Time       On input, the time data read from UEFI to convert
 274                       On output, the time converted to RTC format
 275   @param   RegisterB  Value of Register B of RTC, indicating data mode
 276 **/
 277 VOID
 278 ConvertEfiTimeToRtcTime (
 279   IN OUT EFI_TIME        *Time,
 280   IN     RTC_REGISTER_B  RegisterB
 281   );
 282
 283 /**
 284   Converts time read from RTC to EFI_TIME format defined by UEFI spec.
 285
 286   This function converts raw time data read from RTC to the EFI_TIME format
 287   defined by UEFI spec.
 288   If data mode of RTC is BCD, then converts it to decimal,
 289   If RTC is in 12-hour format, then converts it to 24-hour format.
 290
 291   @param   Time       On input, the time data read from RTC to convert
 292                       On output, the time converted to UEFI format
 293   @param   RegisterB  Value of Register B of RTC, indicating data mode
 294                       and hour format.
 295
 296   @retval  EFI_INVALID_PARAMETER  Parameters passed in are invalid.
 297   @retval  EFI_SUCCESS            Convert RTC time to EFI time successfully.
 298
 299 **/
 300 EFI_STATUS
 301 ConvertRtcTimeToEfiTime (
 302   IN OUT EFI_TIME        *Time,
 303   IN     RTC_REGISTER_B  RegisterB
 304   );
 305
 306 /**
 307   Wait for a period for the RTC to be ready.
 308
 309   @param    Timeout  Tell how long it should take to wait.
 310
 311   @retval   EFI_DEVICE_ERROR   RTC device error.
 312   @retval   EFI_SUCCESS        RTC is updated and ready.
 313 **/
 314 EFI_STATUS
 315 RtcWaitToUpdate (
 316   UINTN  Timeout
 317   );
 318
 319 /**
 320   See if field Day of an EFI_TIME is correct.
 321
 322   @param    Time   Its Day field is to be checked.
 323
 324   @retval   TRUE   Day field of Time is correct.
 325   @retval   FALSE  Day field of Time is NOT correct.
 326 **/
 327 BOOLEAN
 328 DayValid (
 329   IN  EFI_TIME  *Time
 330   );
 331
 332 /**
 333   Check if it is a leapyear.
 334
 335   @param    Time   The time to be checked.
 336
 337   @retval   TRUE   It is a leapyear.
 338   @retval   FALSE  It is NOT a leapyear.
 339 **/
 340 BOOLEAN
 341 IsLeapYear (
 342   IN EFI_TIME  *Time
 343   );
 344
 345 /**
 346   Get the century RTC address from the ACPI FADT table.
 347
 348   @return  The century RTC address or 0 if not found.
 349 **/
 350 UINT8
 351 GetCenturyRtcAddress (
 352   VOID
 353   );
 354
 355 /**
 356   Notification function of ACPI Table change.
 357
 358   This is a notification function registered on ACPI Table change event.
 359   It saves the Century address stored in ACPI FADT table.
 360
 361   @param  Event        Event whose notification function is being invoked.
 362   @param  Context      Pointer to the notification function's context.
 363
 364 **/
 365 VOID
 366 EFIAPI
 367 PcRtcAcpiTableChangeCallback (
 368   IN EFI_EVENT  Event,
 369   IN VOID       *Context
 370   );
 371
 372 #endif