MdeModulePkg/Universal/PcatRealTimeClockRuntimeDxe/PcRtc.h

   1 /** @file
   2   Header file for real time clock driver.
   3
   4 Copyright (c) 2006 - 2007, Intel Corporation
   5 All rights reserved. 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 #include <Guid/GenericPlatformVariable.h>
  24
  25 #include <Library/BaseLib.h>
  26 #include <Library/DebugLib.h>
  27 #include <Library/UefiLib.h>
  28 #include <Library/BaseMemoryLib.h>
  29 #include <Library/IoLib.h>
  30 #include <Library/TimerLib.h>
  31 #include <Library/UefiDriverEntryPoint.h>
  32 #include <Library/UefiBootServicesTableLib.h>
  33 #include <Library/UefiRuntimeLib.h>
  34 #include <Library/UefiRuntimeServicesTableLib.h>
  35 #include <Library/PcdLib.h>
  36
  37
  38 typedef struct {
  39   EFI_LOCK  RtcLock;
  40   INT16     SavedTimeZone;
  41   UINT8     Daylight;
  42 } PC_RTC_MODULE_GLOBALS;
  43
  44 #define PCAT_RTC_ADDRESS_REGISTER 0x70
  45 #define PCAT_RTC_DATA_REGISTER    0x71
  46
  47 //
  48 // Dallas DS12C887 Real Time Clock
  49 //
  50 #define RTC_ADDRESS_SECONDS           0   // R/W  Range 0..59
  51 #define RTC_ADDRESS_SECONDS_ALARM     1   // R/W  Range 0..59
  52 #define RTC_ADDRESS_MINUTES           2   // R/W  Range 0..59
  53 #define RTC_ADDRESS_MINUTES_ALARM     3   // R/W  Range 0..59
  54 #define RTC_ADDRESS_HOURS             4   // R/W  Range 1..12 or 0..23 Bit 7 is AM/PM
  55 #define RTC_ADDRESS_HOURS_ALARM       5   // R/W  Range 1..12 or 0..23 Bit 7 is AM/PM
  56 #define RTC_ADDRESS_DAY_OF_THE_WEEK   6   // R/W  Range 1..7
  57 #define RTC_ADDRESS_DAY_OF_THE_MONTH  7   // R/W  Range 1..31
  58 #define RTC_ADDRESS_MONTH             8   // R/W  Range 1..12
  59 #define RTC_ADDRESS_YEAR              9   // R/W  Range 0..99
  60 #define RTC_ADDRESS_REGISTER_A        10  // R/W[0..6]  R0[7]
  61 #define RTC_ADDRESS_REGISTER_B        11  // R/W
  62 #define RTC_ADDRESS_REGISTER_C        12  // RO
  63 #define RTC_ADDRESS_REGISTER_D        13  // RO
  64 #define RTC_ADDRESS_CENTURY           50  // R/W  Range 19..20 Bit 8 is R/W
  65 //
  66 // Date and time initial values.
  67 // They are used if the RTC values are invalid during driver initialization
  68 //
  69 #define RTC_INIT_SECOND 0
  70 #define RTC_INIT_MINUTE 0
  71 #define RTC_INIT_HOUR   0
  72 #define RTC_INIT_DAY    1
  73 #define RTC_INIT_MONTH  1
  74 #define RTC_INIT_YEAR   2001
  75
  76 //
  77 // Register initial values
  78 //
  79 #define RTC_INIT_REGISTER_A 0x26
  80 #define RTC_INIT_REGISTER_B 0x02
  81 #define RTC_INIT_REGISTER_D 0x0
  82
  83 #pragma pack(1)
  84 //
  85 // Register A
  86 //
  87 typedef struct {
  88   UINT8 RS : 4;   // Rate Selection Bits
  89   UINT8 DV : 3;   // Divisor
  90   UINT8 UIP : 1;  // Update in progress
  91 } RTC_REGISTER_A_BITS;
  92
  93 typedef union {
  94   RTC_REGISTER_A_BITS Bits;
  95   UINT8               Data;
  96 } RTC_REGISTER_A;
  97
  98 //
  99 // Register B
 100 //
 101 typedef struct {
 102   UINT8 DSE : 1;  // 0 - Daylight saving disabled  1 - Daylight savings enabled
 103   UINT8 MIL : 1;  // 0 - 12 hour mode              1 - 24 hour mode
 104   UINT8 DM : 1;   // 0 - BCD Format                1 - Binary Format
 105   UINT8 SQWE : 1; // 0 - Disable SQWE output       1 - Enable SQWE output
 106   UINT8 UIE : 1;  // 0 - Update INT disabled       1 - Update INT enabled
 107   UINT8 AIE : 1;  // 0 - Alarm INT disabled        1 - Alarm INT Enabled
 108   UINT8 PIE : 1;  // 0 - Periodic INT disabled     1 - Periodic INT Enabled
 109   UINT8 SET : 1;  // 0 - Normal operation.         1 - Updates inhibited
 110 } RTC_REGISTER_B_BITS;
 111
 112 typedef union {
 113   RTC_REGISTER_B_BITS Bits;
 114   UINT8               Data;
 115 } RTC_REGISTER_B;
 116
 117 //
 118 // Register C
 119 //
 120 typedef struct {
 121   UINT8 Reserved : 4; // Read as zero.  Can not be written.
 122   UINT8 UF : 1;       // Update End Interrupt Flag
 123   UINT8 AF : 1;       // Alarm Interrupt Flag
 124   UINT8 PF : 1;       // Periodic Interrupt Flag
 125   UINT8 IRQF : 1;     // Iterrupt Request Flag = PF & PIE | AF & AIE | UF & UIE
 126 } RTC_REGISTER_C_BITS;
 127
 128 typedef union {
 129   RTC_REGISTER_C_BITS Bits;
 130   UINT8               Data;
 131 } RTC_REGISTER_C;
 132
 133 //
 134 // Register D
 135 //
 136 typedef struct {
 137   UINT8 Reserved : 7; // Read as zero.  Can not be written.
 138   UINT8 VRT : 1;      // Valid RAM and Time
 139 } RTC_REGISTER_D_BITS;
 140
 141 typedef union {
 142   RTC_REGISTER_D_BITS Bits;
 143   UINT8               Data;
 144 } RTC_REGISTER_D;
 145
 146 #pragma pack()
 147
 148 EFI_STATUS
 149 PcRtcInit (
 150   IN PC_RTC_MODULE_GLOBALS  *Global
 151   )
 152 /*++
 153
 154 Routine Description:
 155
 156   GC_TODO: Add function description
 157
 158 Arguments:
 159
 160   Global  - GC_TODO: add argument description
 161
 162 Returns:
 163
 164   GC_TODO: add return values
 165
 166 --*/
 167 ;
 168
 169 EFI_STATUS
 170 PcRtcSetTime (
 171   IN EFI_TIME               *Time,
 172   IN PC_RTC_MODULE_GLOBALS  *Global
 173   )
 174 /*++
 175
 176 Routine Description:
 177
 178   GC_TODO: Add function description
 179
 180 Arguments:
 181
 182   Time    - GC_TODO: add argument description
 183   Global  - GC_TODO: add argument description
 184
 185 Returns:
 186
 187   GC_TODO: add return values
 188
 189 --*/
 190 ;
 191
 192 EFI_STATUS
 193 PcRtcGetTime (
 194   OUT EFI_TIME              *Time,
 195   IN  EFI_TIME_CAPABILITIES *Capabilities,
 196   IN  PC_RTC_MODULE_GLOBALS *Global
 197   )
 198 /*++
 199
 200 Routine Description:
 201
 202   GC_TODO: Add function description
 203
 204 Arguments:
 205
 206   Time          - GC_TODO: add argument description
 207   Capabilities  - GC_TODO: add argument description
 208   Global        - GC_TODO: add argument description
 209
 210 Returns:
 211
 212   GC_TODO: add return values
 213
 214 --*/
 215 ;
 216
 217 EFI_STATUS
 218 PcRtcSetWakeupTime (
 219   IN BOOLEAN                Enable,
 220   OUT EFI_TIME              *Time,
 221   IN  PC_RTC_MODULE_GLOBALS *Global
 222   )
 223 /*++
 224
 225 Routine Description:
 226
 227   GC_TODO: Add function description
 228
 229 Arguments:
 230
 231   Enable  - GC_TODO: add argument description
 232   Time    - GC_TODO: add argument description
 233   Global  - GC_TODO: add argument description
 234
 235 Returns:
 236
 237   GC_TODO: add return values
 238
 239 --*/
 240 ;
 241
 242 EFI_STATUS
 243 PcRtcGetWakeupTime (
 244   OUT BOOLEAN               *Enabled,
 245   OUT BOOLEAN               *Pending,
 246   OUT EFI_TIME              *Time,
 247   IN  PC_RTC_MODULE_GLOBALS *Global
 248   )
 249 /*++
 250
 251 Routine Description:
 252
 253   GC_TODO: Add function description
 254
 255 Arguments:
 256
 257   Enabled - GC_TODO: add argument description
 258   Pending - GC_TODO: add argument description
 259   Time    - GC_TODO: add argument description
 260   Global  - GC_TODO: add argument description
 261
 262 Returns:
 263
 264   GC_TODO: add return values
 265
 266 --*/
 267 ;
 268
 269 EFI_STATUS
 270 EFIAPI
 271 InitializePcRtc (
 272   IN EFI_HANDLE                            ImageHandle,
 273   IN EFI_SYSTEM_TABLE                      *SystemTable
 274   )
 275 /*++
 276
 277 Routine Description:
 278
 279   GC_TODO: Add function description
 280
 281 Arguments:
 282
 283   ImageHandle - GC_TODO: add argument description
 284   SystemTable - GC_TODO: add argument description
 285
 286 Returns:
 287
 288   GC_TODO: add return values
 289
 290 --*/
 291 ;
 292
 293 UINT8
 294 BcdToDecimal (
 295   IN  UINT8 BcdValue
 296   )
 297 /*++
 298
 299 Routine Description:
 300
 301   GC_TODO: Add function description
 302
 303 Arguments:
 304
 305   BcdValue  - GC_TODO: add argument description
 306
 307 Returns:
 308
 309   GC_TODO: add return values
 310
 311 --*/
 312 ;
 313
 314 EFI_STATUS
 315 RtcTimeFieldsValid (
 316   IN EFI_TIME *Time
 317   )
 318 /*++
 319
 320 Routine Description:
 321
 322   GC_TODO: Add function description
 323
 324 Arguments:
 325
 326   Time  - GC_TODO: add argument description
 327
 328 Returns:
 329
 330   GC_TODO: add return values
 331
 332 --*/
 333 ;
 334
 335 UINT8
 336 DecimaltoBcd (
 337   IN  UINT8 DecValue
 338   )
 339 /*++
 340
 341 Routine Description:
 342
 343   GC_TODO: Add function description
 344
 345 Arguments:
 346
 347   DecValue  - GC_TODO: add argument description
 348
 349 Returns:
 350
 351   GC_TODO: add return values
 352
 353 --*/
 354 ;
 355
 356 VOID
 357 ConvertEfiTimeToRtcTime (
 358   IN EFI_TIME       *Time,
 359   IN RTC_REGISTER_B RegisterB,
 360   IN UINT8          *Century
 361   )
 362 /*++
 363
 364 Routine Description:
 365
 366   GC_TODO: Add function description
 367
 368 Arguments:
 369
 370   Time      - GC_TODO: add argument description
 371   RegisterB - GC_TODO: add argument description
 372   Century   - GC_TODO: add argument description
 373
 374 Returns:
 375
 376   GC_TODO: add return values
 377
 378 --*/
 379 ;
 380
 381 EFI_STATUS
 382 RtcTestCenturyRegister (
 383   VOID
 384   )
 385 /*++
 386
 387 Routine Description:
 388
 389   GC_TODO: Add function description
 390
 391 Arguments:
 392
 393   None
 394
 395 Returns:
 396
 397   GC_TODO: add return values
 398
 399 --*/
 400 ;
 401
 402 /**
 403   Converts time read from RTC to EFI_TIME format defined by UEFI spec.
 404
 405   This function converts raw time data read from RTC to the EFI_TIME format
 406   defined by UEFI spec.
 407   If data mode of RTC is BCD, then converts it to decimal,
 408   If RTC is in 12-hour format, then converts it to 24-hour format.
 409
 410   @param   Time       On input, the time data read from RTC to convert
 411                       On output, the time converted to UEFI format
 412   @param   Century    Value of century read from RTC.
 413   @param   RegisterB  Value of Register B of RTC, indicating data mode
 414                       and hour format.
 415
 416 **/
 417 EFI_STATUS
 418 ConvertRtcTimeToEfiTime (
 419   IN OUT EFI_TIME        *Time,
 420   IN     UINT8           Century,
 421   IN     RTC_REGISTER_B  RegisterB
 422   );
 423
 424 EFI_STATUS
 425 RtcWaitToUpdate (
 426   UINTN Timeout
 427   )
 428 /*++
 429
 430 Routine Description:
 431
 432   GC_TODO: Add function description
 433
 434 Arguments:
 435
 436   Timeout - GC_TODO: add argument description
 437
 438 Returns:
 439
 440   GC_TODO: add return values
 441
 442 --*/
 443 ;
 444
 445 UINT8
 446 RtcSaveContext (
 447   IN  PC_RTC_MODULE_GLOBALS  *Global
 448   )
 449 /*++
 450
 451 Routine Description:
 452
 453   GC_TODO: Add function description
 454
 455 Arguments:
 456
 457   Global  - GC_TODO: add argument description
 458
 459 Returns:
 460
 461   GC_TODO: add return values
 462
 463 --*/
 464 ;
 465
 466 VOID
 467 RtcRestoreContext (
 468   IN  UINT8                 SavedAddressRegister,
 469   IN  PC_RTC_MODULE_GLOBALS *Global
 470   )
 471 /*++
 472
 473 Routine Description:
 474
 475   GC_TODO: Add function description
 476
 477 Arguments:
 478
 479   SavedAddressRegister  - GC_TODO: add argument description
 480   Global                - GC_TODO: add argument description
 481
 482 Returns:
 483
 484   GC_TODO: add return values
 485
 486 --*/
 487 ;
 488
 489 BOOLEAN
 490 DayValid (
 491   IN  EFI_TIME  *Time
 492   );
 493
 494 BOOLEAN
 495 IsLeapYear (
 496   IN EFI_TIME   *Time
 497   );
 498
 499 #endif