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