PcAtChipsetPkg/PcatRealTimeClockRuntimeDxe/PcRtc.h

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