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