PcRtc.h 11 KB

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