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