2 Header file for real time clock driver.
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5 Copyright (c) 2017, AMD Inc. All rights reserved.<BR>
7 SPDX-License-Identifier: BSD-2-Clause-Patent
16 #include <Guid/Acpi.h>
18 #include <Protocol/RealTimeClock.h>
20 #include <Library/BaseLib.h>
21 #include <Library/DebugLib.h>
22 #include <Library/UefiLib.h>
23 #include <Library/BaseMemoryLib.h>
24 #include <Library/IoLib.h>
25 #include <Library/TimerLib.h>
26 #include <Library/UefiDriverEntryPoint.h>
27 #include <Library/UefiBootServicesTableLib.h>
28 #include <Library/UefiRuntimeLib.h>
29 #include <Library/UefiRuntimeServicesTableLib.h>
30 #include <Library/PcdLib.h>
31 #include <Library/ReportStatusCodeLib.h>
37 UINT8 CenturyRtcAddress
;
38 } PC_RTC_MODULE_GLOBALS
;
40 extern PC_RTC_MODULE_GLOBALS mModuleGlobal
;
43 // Dallas DS12C887 Real Time Clock
45 #define RTC_ADDRESS_SECONDS 0 // R/W Range 0..59
46 #define RTC_ADDRESS_SECONDS_ALARM 1 // R/W Range 0..59
47 #define RTC_ADDRESS_MINUTES 2 // R/W Range 0..59
48 #define RTC_ADDRESS_MINUTES_ALARM 3 // R/W Range 0..59
49 #define RTC_ADDRESS_HOURS 4 // R/W Range 1..12 or 0..23 Bit 7 is AM/PM
50 #define RTC_ADDRESS_HOURS_ALARM 5 // R/W Range 1..12 or 0..23 Bit 7 is AM/PM
51 #define RTC_ADDRESS_DAY_OF_THE_WEEK 6 // R/W Range 1..7
52 #define RTC_ADDRESS_DAY_OF_THE_MONTH 7 // R/W Range 1..31
53 #define RTC_ADDRESS_MONTH 8 // R/W Range 1..12
54 #define RTC_ADDRESS_YEAR 9 // R/W Range 0..99
55 #define RTC_ADDRESS_REGISTER_A 10 // R/W[0..6] R0[7]
56 #define RTC_ADDRESS_REGISTER_B 11 // R/W
57 #define RTC_ADDRESS_REGISTER_C 12 // RO
58 #define RTC_ADDRESS_REGISTER_D 13 // RO
60 // Date and time initial values.
61 // They are used if the RTC values are invalid during driver initialization
63 #define RTC_INIT_SECOND 0
64 #define RTC_INIT_MINUTE 0
65 #define RTC_INIT_HOUR 0
66 #define RTC_INIT_DAY 1
67 #define RTC_INIT_MONTH 1
74 UINT8 Rs
: 4; // Rate Selection Bits
75 UINT8 Dv
: 3; // Divisor
76 UINT8 Uip
: 1; // Update in progress
77 } RTC_REGISTER_A_BITS
;
80 RTC_REGISTER_A_BITS Bits
;
88 UINT8 Dse
: 1; // 0 - Daylight saving disabled 1 - Daylight savings enabled
89 UINT8 Mil
: 1; // 0 - 12 hour mode 1 - 24 hour mode
90 UINT8 Dm
: 1; // 0 - BCD Format 1 - Binary Format
91 UINT8 Sqwe
: 1; // 0 - Disable SQWE output 1 - Enable SQWE output
92 UINT8 Uie
: 1; // 0 - Update INT disabled 1 - Update INT enabled
93 UINT8 Aie
: 1; // 0 - Alarm INT disabled 1 - Alarm INT Enabled
94 UINT8 Pie
: 1; // 0 - Periodic INT disabled 1 - Periodic INT Enabled
95 UINT8 Set
: 1; // 0 - Normal operation. 1 - Updates inhibited
96 } RTC_REGISTER_B_BITS
;
99 RTC_REGISTER_B_BITS Bits
;
107 UINT8 Reserved
: 4; // Read as zero. Can not be written.
108 UINT8 Uf
: 1; // Update End Interrupt Flag
109 UINT8 Af
: 1; // Alarm Interrupt Flag
110 UINT8 Pf
: 1; // Periodic Interrupt Flag
111 UINT8 Irqf
: 1; // Interrupt Request Flag = PF & PIE | AF & AIE | UF & UIE
112 } RTC_REGISTER_C_BITS
;
115 RTC_REGISTER_C_BITS Bits
;
123 UINT8 Reserved
: 7; // Read as zero. Can not be written.
124 UINT8 Vrt
: 1; // Valid RAM and Time
125 } RTC_REGISTER_D_BITS
;
128 RTC_REGISTER_D_BITS Bits
;
137 @param Global For global use inside this module.
139 @retval EFI_DEVICE_ERROR Initialization failed due to device error.
140 @retval EFI_SUCCESS Initialization successful.
145 IN PC_RTC_MODULE_GLOBALS
*Global
149 Sets the current local time and date information.
151 @param Time A pointer to the current time.
152 @param Global For global use inside this module.
154 @retval EFI_SUCCESS The operation completed successfully.
155 @retval EFI_INVALID_PARAMETER A time field is out of range.
156 @retval EFI_DEVICE_ERROR The time could not be set due due to hardware error.
162 IN PC_RTC_MODULE_GLOBALS
*Global
166 Returns the current time and date information, and the time-keeping capabilities
167 of the hardware platform.
169 @param Time A pointer to storage to receive a snapshot of the current time.
170 @param Capabilities An optional pointer to a buffer to receive the real time clock
171 device's capabilities.
172 @param Global For global use inside this module.
174 @retval EFI_SUCCESS The operation completed successfully.
175 @retval EFI_INVALID_PARAMETER Time is NULL.
176 @retval EFI_DEVICE_ERROR The time could not be retrieved due to hardware error.
182 OUT EFI_TIME_CAPABILITIES
*Capabilities OPTIONAL
,
183 IN PC_RTC_MODULE_GLOBALS
*Global
187 Sets the system wakeup alarm clock time.
189 @param Enabled Enable or disable the wakeup alarm.
190 @param Time If Enable is TRUE, the time to set the wakeup alarm for.
191 If Enable is FALSE, then this parameter is optional, and may be NULL.
192 @param Global For global use inside this module.
194 @retval EFI_SUCCESS If Enable is TRUE, then the wakeup alarm was enabled.
195 If Enable is FALSE, then the wakeup alarm was disabled.
196 @retval EFI_INVALID_PARAMETER A time field is out of range.
197 @retval EFI_DEVICE_ERROR The wakeup time could not be set due to a hardware error.
198 @retval EFI_UNSUPPORTED A wakeup timer is not supported on this platform.
204 IN EFI_TIME
*Time OPTIONAL
,
205 IN PC_RTC_MODULE_GLOBALS
*Global
209 Returns the current wakeup alarm clock setting.
211 @param Enabled Indicates if the alarm is currently enabled or disabled.
212 @param Pending Indicates if the alarm signal is pending and requires acknowledgement.
213 @param Time The current alarm setting.
214 @param Global For global use inside this module.
216 @retval EFI_SUCCESS The alarm settings were returned.
217 @retval EFI_INVALID_PARAMETER Enabled is NULL.
218 @retval EFI_INVALID_PARAMETER Pending is NULL.
219 @retval EFI_INVALID_PARAMETER Time is NULL.
220 @retval EFI_DEVICE_ERROR The wakeup time could not be retrieved due to a hardware error.
221 @retval EFI_UNSUPPORTED A wakeup timer is not supported on this platform.
226 OUT BOOLEAN
*Enabled
,
227 OUT BOOLEAN
*Pending
,
229 IN PC_RTC_MODULE_GLOBALS
*Global
233 The user Entry Point for PcRTC module.
235 This is the entry point for PcRTC module. It installs the UEFI runtime service
236 including GetTime(),SetTime(),GetWakeupTime(),and SetWakeupTime().
238 @param ImageHandle The firmware allocated handle for the EFI image.
239 @param SystemTable A pointer to the EFI System Table.
241 @retval EFI_SUCCESS The entry point is executed successfully.
242 @retval Others Some error occurs when executing this entry point.
248 IN EFI_HANDLE ImageHandle
,
249 IN EFI_SYSTEM_TABLE
*SystemTable
253 See if all fields of a variable of EFI_TIME type is correct.
255 @param Time The time to be checked.
257 @retval EFI_INVALID_PARAMETER Some fields of Time are not correct.
258 @retval EFI_SUCCESS Time is a valid EFI_TIME variable.
267 Converts time from EFI_TIME format defined by UEFI spec to RTC format.
269 This function converts time from EFI_TIME format defined by UEFI spec to RTC format.
270 If data mode of RTC is BCD, then converts EFI_TIME to it.
271 If RTC is in 12-hour format, then converts EFI_TIME to it.
273 @param Time On input, the time data read from UEFI to convert
274 On output, the time converted to RTC format
275 @param RegisterB Value of Register B of RTC, indicating data mode
278 ConvertEfiTimeToRtcTime (
279 IN OUT EFI_TIME
*Time
,
280 IN RTC_REGISTER_B RegisterB
284 Converts time read from RTC to EFI_TIME format defined by UEFI spec.
286 This function converts raw time data read from RTC to the EFI_TIME format
287 defined by UEFI spec.
288 If data mode of RTC is BCD, then converts it to decimal,
289 If RTC is in 12-hour format, then converts it to 24-hour format.
291 @param Time On input, the time data read from RTC to convert
292 On output, the time converted to UEFI format
293 @param RegisterB Value of Register B of RTC, indicating data mode
296 @retval EFI_INVALID_PARAMETER Parameters passed in are invalid.
297 @retval EFI_SUCCESS Convert RTC time to EFI time successfully.
301 ConvertRtcTimeToEfiTime (
302 IN OUT EFI_TIME
*Time
,
303 IN RTC_REGISTER_B RegisterB
307 Wait for a period for the RTC to be ready.
309 @param Timeout Tell how long it should take to wait.
311 @retval EFI_DEVICE_ERROR RTC device error.
312 @retval EFI_SUCCESS RTC is updated and ready.
320 See if field Day of an EFI_TIME is correct.
322 @param Time Its Day field is to be checked.
324 @retval TRUE Day field of Time is correct.
325 @retval FALSE Day field of Time is NOT correct.
333 Check if it is a leapyear.
335 @param Time The time to be checked.
337 @retval TRUE It is a leapyear.
338 @retval FALSE It is NOT a leapyear.
346 Get the century RTC address from the ACPI FADT table.
348 @return The century RTC address or 0 if not found.
351 GetCenturyRtcAddress (
356 Notification function of ACPI Table change.
358 This is a notification function registered on ACPI Table change event.
359 It saves the Century address stored in ACPI FADT table.
361 @param Event Event whose notification function is being invoked.
362 @param Context Pointer to the notification function's context.
367 PcRtcAcpiTableChangeCallback (