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