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