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