PcAtChipsetPkg/PcatRealTimeClockRuntimeDxe/PcRtc.h

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