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