Add logic to check uninitialized RTC value in PcRtc driver in MdeModulePkg.
[people/mcb30/edk2.git] / edk2 / MdeModulePkg / Universal / PcatRealTimeClockRuntimeDxe / PcRtc.h
1 /** @file\r
2   Header file for real time clock driver.\r
3 \r
4 Copyright (c) 2006 - 2007, Intel Corporation\r
5 All rights reserved. This program and the accompanying materials\r
6 are licensed and made available under the terms and conditions of the BSD License\r
7 which accompanies this distribution.  The full text of the license may be found at\r
8 http://opensource.org/licenses/bsd-license.php\r
9 \r
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
12 \r
13 **/\r
14 \r
15 \r
16 #ifndef _RTC_H_\r
17 #define _RTC_H_\r
18 \r
19 \r
20 #include <PiDxe.h>\r
21 \r
22 #include <Protocol/RealTimeClock.h>\r
23 #include <Guid/GenericPlatformVariable.h>\r
24 \r
25 #include <Library/BaseLib.h>\r
26 #include <Library/DebugLib.h>\r
27 #include <Library/UefiLib.h>\r
28 #include <Library/BaseMemoryLib.h>\r
29 #include <Library/IoLib.h>\r
30 #include <Library/TimerLib.h>\r
31 #include <Library/UefiDriverEntryPoint.h>\r
32 #include <Library/UefiBootServicesTableLib.h>\r
33 #include <Library/UefiRuntimeLib.h>\r
34 #include <Library/UefiRuntimeServicesTableLib.h>\r
35 \r
36 \r
37 typedef struct {\r
38   EFI_LOCK  RtcLock;\r
39   INT16     SavedTimeZone;\r
40   UINT8     Daylight;\r
41 } PC_RTC_MODULE_GLOBALS;\r
42 \r
43 #define PCAT_RTC_ADDRESS_REGISTER 0x70\r
44 #define PCAT_RTC_DATA_REGISTER    0x71\r
45 \r
46 //\r
47 // Dallas DS12C887 Real Time Clock\r
48 //\r
49 #define RTC_ADDRESS_SECONDS           0   // R/W  Range 0..59\r
50 #define RTC_ADDRESS_SECONDS_ALARM     1   // R/W  Range 0..59\r
51 #define RTC_ADDRESS_MINUTES           2   // R/W  Range 0..59\r
52 #define RTC_ADDRESS_MINUTES_ALARM     3   // R/W  Range 0..59\r
53 #define RTC_ADDRESS_HOURS             4   // R/W  Range 1..12 or 0..23 Bit 7 is AM/PM\r
54 #define RTC_ADDRESS_HOURS_ALARM       5   // R/W  Range 1..12 or 0..23 Bit 7 is AM/PM\r
55 #define RTC_ADDRESS_DAY_OF_THE_WEEK   6   // R/W  Range 1..7\r
56 #define RTC_ADDRESS_DAY_OF_THE_MONTH  7   // R/W  Range 1..31\r
57 #define RTC_ADDRESS_MONTH             8   // R/W  Range 1..12\r
58 #define RTC_ADDRESS_YEAR              9   // R/W  Range 0..99\r
59 #define RTC_ADDRESS_REGISTER_A        10  // R/W[0..6]  R0[7]\r
60 #define RTC_ADDRESS_REGISTER_B        11  // R/W\r
61 #define RTC_ADDRESS_REGISTER_C        12  // RO\r
62 #define RTC_ADDRESS_REGISTER_D        13  // RO\r
63 #define RTC_ADDRESS_CENTURY           50  // R/W  Range 19..20 Bit 8 is R/W\r
64 //\r
65 // Date and time initial values.\r
66 // They are used if the RTC values are invalid during driver initialization\r
67 //\r
68 #define RTC_INIT_SECOND 0\r
69 #define RTC_INIT_MINUTE 0\r
70 #define RTC_INIT_HOUR   0\r
71 #define RTC_INIT_DAY    1\r
72 #define RTC_INIT_MONTH  1\r
73 #define RTC_INIT_YEAR   2001\r
74 \r
75 //\r
76 // Register initial values\r
77 //\r
78 #define RTC_INIT_REGISTER_A 0x26\r
79 #define RTC_INIT_REGISTER_B 0x02\r
80 #define RTC_INIT_REGISTER_D 0x0\r
81 \r
82 #pragma pack(1)\r
83 //\r
84 // Register A\r
85 //\r
86 typedef struct {\r
87   UINT8 RS : 4;   // Rate Selection Bits\r
88   UINT8 DV : 3;   // Divisor\r
89   UINT8 UIP : 1;  // Update in progress\r
90 } RTC_REGISTER_A_BITS;\r
91 \r
92 typedef union {\r
93   RTC_REGISTER_A_BITS Bits;\r
94   UINT8               Data;\r
95 } RTC_REGISTER_A;\r
96 \r
97 //\r
98 // Register B\r
99 //\r
100 typedef struct {\r
101   UINT8 DSE : 1;  // 0 - Daylight saving disabled  1 - Daylight savings enabled\r
102   UINT8 MIL : 1;  // 0 - 12 hour mode              1 - 24 hour mode\r
103   UINT8 DM : 1;   // 0 - BCD Format                1 - Binary Format\r
104   UINT8 SQWE : 1; // 0 - Disable SQWE output       1 - Enable SQWE output\r
105   UINT8 UIE : 1;  // 0 - Update INT disabled       1 - Update INT enabled\r
106   UINT8 AIE : 1;  // 0 - Alarm INT disabled        1 - Alarm INT Enabled\r
107   UINT8 PIE : 1;  // 0 - Periodic INT disabled     1 - Periodic INT Enabled\r
108   UINT8 SET : 1;  // 0 - Normal operation.         1 - Updates inhibited\r
109 } RTC_REGISTER_B_BITS;\r
110 \r
111 typedef union {\r
112   RTC_REGISTER_B_BITS Bits;\r
113   UINT8               Data;\r
114 } RTC_REGISTER_B;\r
115 \r
116 //\r
117 // Register C\r
118 //\r
119 typedef struct {\r
120   UINT8 Reserved : 4; // Read as zero.  Can not be written.\r
121   UINT8 UF : 1;       // Update End Interrupt Flag\r
122   UINT8 AF : 1;       // Alarm Interrupt Flag\r
123   UINT8 PF : 1;       // Periodic Interrupt Flag\r
124   UINT8 IRQF : 1;     // Iterrupt Request Flag = PF & PIE | AF & AIE | UF & UIE\r
125 } RTC_REGISTER_C_BITS;\r
126 \r
127 typedef union {\r
128   RTC_REGISTER_C_BITS Bits;\r
129   UINT8               Data;\r
130 } RTC_REGISTER_C;\r
131 \r
132 //\r
133 // Register D\r
134 //\r
135 typedef struct {\r
136   UINT8 Reserved : 7; // Read as zero.  Can not be written.\r
137   UINT8 VRT : 1;      // Valid RAM and Time\r
138 } RTC_REGISTER_D_BITS;\r
139 \r
140 typedef union {\r
141   RTC_REGISTER_D_BITS Bits;\r
142   UINT8               Data;\r
143 } RTC_REGISTER_D;\r
144 \r
145 #pragma pack()\r
146 \r
147 EFI_STATUS\r
148 PcRtcInit (\r
149   IN PC_RTC_MODULE_GLOBALS  *Global\r
150   )\r
151 /*++\r
152 \r
153 Routine Description:\r
154 \r
155   GC_TODO: Add function description\r
156 \r
157 Arguments:\r
158 \r
159   Global  - GC_TODO: add argument description\r
160 \r
161 Returns:\r
162 \r
163   GC_TODO: add return values\r
164 \r
165 --*/\r
166 ;\r
167 \r
168 EFI_STATUS\r
169 PcRtcSetTime (\r
170   IN EFI_TIME               *Time,\r
171   IN PC_RTC_MODULE_GLOBALS  *Global\r
172   )\r
173 /*++\r
174 \r
175 Routine Description:\r
176 \r
177   GC_TODO: Add function description\r
178 \r
179 Arguments:\r
180 \r
181   Time    - GC_TODO: add argument description\r
182   Global  - GC_TODO: add argument description\r
183 \r
184 Returns:\r
185 \r
186   GC_TODO: add return values\r
187 \r
188 --*/\r
189 ;\r
190 \r
191 EFI_STATUS\r
192 PcRtcGetTime (\r
193   OUT EFI_TIME              *Time,\r
194   IN  EFI_TIME_CAPABILITIES *Capabilities,\r
195   IN  PC_RTC_MODULE_GLOBALS *Global\r
196   )\r
197 /*++\r
198 \r
199 Routine Description:\r
200 \r
201   GC_TODO: Add function description\r
202 \r
203 Arguments:\r
204 \r
205   Time          - GC_TODO: add argument description\r
206   Capabilities  - GC_TODO: add argument description\r
207   Global        - GC_TODO: add argument description\r
208 \r
209 Returns:\r
210 \r
211   GC_TODO: add return values\r
212 \r
213 --*/\r
214 ;\r
215 \r
216 EFI_STATUS\r
217 PcRtcSetWakeupTime (\r
218   IN BOOLEAN                Enable,\r
219   OUT EFI_TIME              *Time,\r
220   IN  PC_RTC_MODULE_GLOBALS *Global\r
221   )\r
222 /*++\r
223 \r
224 Routine Description:\r
225 \r
226   GC_TODO: Add function description\r
227 \r
228 Arguments:\r
229 \r
230   Enable  - GC_TODO: add argument description\r
231   Time    - GC_TODO: add argument description\r
232   Global  - GC_TODO: add argument description\r
233 \r
234 Returns:\r
235 \r
236   GC_TODO: add return values\r
237 \r
238 --*/\r
239 ;\r
240 \r
241 EFI_STATUS\r
242 PcRtcGetWakeupTime (\r
243   OUT BOOLEAN               *Enabled,\r
244   OUT BOOLEAN               *Pending,\r
245   OUT EFI_TIME              *Time,\r
246   IN  PC_RTC_MODULE_GLOBALS *Global\r
247   )\r
248 /*++\r
249 \r
250 Routine Description:\r
251 \r
252   GC_TODO: Add function description\r
253 \r
254 Arguments:\r
255 \r
256   Enabled - GC_TODO: add argument description\r
257   Pending - GC_TODO: add argument description\r
258   Time    - GC_TODO: add argument description\r
259   Global  - GC_TODO: add argument description\r
260 \r
261 Returns:\r
262 \r
263   GC_TODO: add return values\r
264 \r
265 --*/\r
266 ;\r
267 \r
268 EFI_STATUS\r
269 EFIAPI\r
270 InitializePcRtc (\r
271   IN EFI_HANDLE                            ImageHandle,\r
272   IN EFI_SYSTEM_TABLE                      *SystemTable\r
273   )\r
274 /*++\r
275 \r
276 Routine Description:\r
277 \r
278   GC_TODO: Add function description\r
279 \r
280 Arguments:\r
281 \r
282   ImageHandle - GC_TODO: add argument description\r
283   SystemTable - GC_TODO: add argument description\r
284 \r
285 Returns:\r
286 \r
287   GC_TODO: add return values\r
288 \r
289 --*/\r
290 ;\r
291 \r
292 UINT8\r
293 BcdToDecimal (\r
294   IN  UINT8 BcdValue\r
295   )\r
296 /*++\r
297 \r
298 Routine Description:\r
299 \r
300   GC_TODO: Add function description\r
301 \r
302 Arguments:\r
303 \r
304   BcdValue  - GC_TODO: add argument description\r
305 \r
306 Returns:\r
307 \r
308   GC_TODO: add return values\r
309 \r
310 --*/\r
311 ;\r
312 \r
313 EFI_STATUS\r
314 RtcTimeFieldsValid (\r
315   IN EFI_TIME *Time\r
316   )\r
317 /*++\r
318 \r
319 Routine Description:\r
320 \r
321   GC_TODO: Add function description\r
322 \r
323 Arguments:\r
324 \r
325   Time  - GC_TODO: add argument description\r
326 \r
327 Returns:\r
328 \r
329   GC_TODO: add return values\r
330 \r
331 --*/\r
332 ;\r
333 \r
334 UINT8\r
335 DecimaltoBcd (\r
336   IN  UINT8 DecValue\r
337   )\r
338 /*++\r
339 \r
340 Routine Description:\r
341 \r
342   GC_TODO: Add function description\r
343 \r
344 Arguments:\r
345 \r
346   DecValue  - GC_TODO: add argument description\r
347 \r
348 Returns:\r
349 \r
350   GC_TODO: add return values\r
351 \r
352 --*/\r
353 ;\r
354 \r
355 VOID\r
356 ConvertEfiTimeToRtcTime (\r
357   IN EFI_TIME       *Time,\r
358   IN RTC_REGISTER_B RegisterB,\r
359   IN UINT8          *Century\r
360   )\r
361 /*++\r
362 \r
363 Routine Description:\r
364 \r
365   GC_TODO: Add function description\r
366 \r
367 Arguments:\r
368 \r
369   Time      - GC_TODO: add argument description\r
370   RegisterB - GC_TODO: add argument description\r
371   Century   - GC_TODO: add argument description\r
372 \r
373 Returns:\r
374 \r
375   GC_TODO: add return values\r
376 \r
377 --*/\r
378 ;\r
379 \r
380 EFI_STATUS\r
381 RtcTestCenturyRegister (\r
382   VOID\r
383   )\r
384 /*++\r
385 \r
386 Routine Description:\r
387 \r
388   GC_TODO: Add function description\r
389 \r
390 Arguments:\r
391 \r
392   None\r
393 \r
394 Returns:\r
395 \r
396   GC_TODO: add return values\r
397 \r
398 --*/\r
399 ;\r
400 \r
401 /**\r
402   Converts time read from RTC to EFI_TIME format defined by UEFI spec.\r
403 \r
404   This function converts raw time data read from RTC to the EFI_TIME format\r
405   defined by UEFI spec.\r
406   If data mode of RTC is BCD, then converts it to decimal,\r
407   If RTC is in 12-hour format, then converts it to 24-hour format.\r
408 \r
409   @param   Time       On input, the time data read from RTC to convert\r
410                       On output, the time converted to UEFI format\r
411   @param   Century    Value of century read from RTC.\r
412   @param   RegisterB  Value of Register B of RTC, indicating data mode\r
413                       and hour format.\r
414 \r
415 **/\r
416 EFI_STATUS\r
417 ConvertRtcTimeToEfiTime (\r
418   IN OUT EFI_TIME        *Time,\r
419   IN     UINT8           Century,\r
420   IN     RTC_REGISTER_B  RegisterB\r
421   )\r
422 ;\r
423 \r
424 EFI_STATUS\r
425 RtcWaitToUpdate (\r
426   UINTN Timeout\r
427   )\r
428 /*++\r
429 \r
430 Routine Description:\r
431 \r
432   GC_TODO: Add function description\r
433 \r
434 Arguments:\r
435 \r
436   Timeout - GC_TODO: add argument description\r
437 \r
438 Returns:\r
439 \r
440   GC_TODO: add return values\r
441 \r
442 --*/\r
443 ;\r
444 \r
445 UINT8\r
446 RtcSaveContext (\r
447   IN  PC_RTC_MODULE_GLOBALS  *Global\r
448   )\r
449 /*++\r
450 \r
451 Routine Description:\r
452 \r
453   GC_TODO: Add function description\r
454 \r
455 Arguments:\r
456 \r
457   Global  - GC_TODO: add argument description\r
458 \r
459 Returns:\r
460 \r
461   GC_TODO: add return values\r
462 \r
463 --*/\r
464 ;\r
465 \r
466 VOID\r
467 RtcRestoreContext (\r
468   IN  UINT8                 SavedAddressRegister,\r
469   IN  PC_RTC_MODULE_GLOBALS *Global\r
470   )\r
471 /*++\r
472 \r
473 Routine Description:\r
474 \r
475   GC_TODO: Add function description\r
476 \r
477 Arguments:\r
478 \r
479   SavedAddressRegister  - GC_TODO: add argument description\r
480   Global                - GC_TODO: add argument description\r
481 \r
482 Returns:\r
483 \r
484   GC_TODO: add return values\r
485 \r
486 --*/\r
487 ;\r
488 \r
489 BOOLEAN\r
490 DayValid (\r
491   IN  EFI_TIME  *Time\r
492   );\r
493 \r
494 BOOLEAN\r
495 IsLeapYear (\r
496   IN EFI_TIME   *Time\r
497   );\r
498 \r
499 #endif\r