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