Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 1 | ========================== |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 2 | EFI Real Time Clock driver |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 3 | ========================== |
| 4 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 5 | S. Eranian <eranian@hpl.hp.com> |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 6 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 7 | March 2000 |
| 8 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 9 | 1. Introduction |
| 10 | =============== |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 11 | |
| 12 | This document describes the efirtc.c driver has provided for |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 13 | the IA-64 platform. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 14 | |
| 15 | The purpose of this driver is to supply an API for kernel and user applications |
| 16 | to get access to the Time Service offered by EFI version 0.92. |
| 17 | |
| 18 | EFI provides 4 calls one can make once the OS is booted: GetTime(), |
| 19 | SetTime(), GetWakeupTime(), SetWakeupTime() which are all supported by this |
| 20 | driver. We describe those calls as well the design of the driver in the |
| 21 | following sections. |
| 22 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 23 | 2. Design Decisions |
| 24 | =================== |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 25 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 26 | The original ideas was to provide a very simple driver to get access to, |
| 27 | at first, the time of day service. This is required in order to access, in a |
| 28 | portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 29 | to initialize the system view of the time during boot. |
| 30 | |
| 31 | Because we wanted to minimize the impact on existing user-level apps using |
| 32 | the CMOS clock, we decided to expose an API that was very similar to the one |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 33 | used today with the legacy RTC driver (driver/char/rtc.c). However, because |
Paolo Ornati | 670e9f3 | 2006-10-03 22:57:56 +0200 | [diff] [blame] | 34 | EFI provides a simpler services, not all ioctl() are available. Also |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 35 | new ioctl()s have been introduced for things that EFI provides but not the |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 36 | legacy. |
| 37 | |
| 38 | EFI uses a slightly different way of representing the time, noticeably |
| 39 | the reference date is different. Year is the using the full 4-digit format. |
| 40 | The Epoch is January 1st 1998. For backward compatibility reasons we don't |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 41 | expose this new way of representing time. Instead we use something very |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 42 | similar to the struct tm, i.e. struct rtc_time, as used by hwclock. |
| 43 | One of the reasons for doing it this way is to allow for EFI to still evolve |
| 44 | without necessarily impacting any of the user applications. The decoupling |
| 45 | enables flexibility and permits writing wrapper code is ncase things change. |
| 46 | |
| 47 | The driver exposes two interfaces, one via the device file and a set of |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 48 | ioctl()s. The other is read-only via the /proc filesystem. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 49 | |
| 50 | As of today we don't offer a /proc/sys interface. |
| 51 | |
| 52 | To allow for a uniform interface between the legacy RTC and EFI time service, |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 53 | we have created the include/linux/rtc.h header file to contain only the |
| 54 | "public" API of the two drivers. The specifics of the legacy RTC are still |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 55 | in include/linux/mc146818rtc.h. |
| 56 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 57 | |
| 58 | 3. Time of day service |
| 59 | ====================== |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 60 | |
| 61 | The part of the driver gives access to the time of day service of EFI. |
| 62 | Two ioctl()s, compatible with the legacy RTC calls: |
| 63 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 64 | Read the CMOS clock:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 65 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 66 | ioctl(d, RTC_RD_TIME, &rtc); |
| 67 | |
| 68 | Write the CMOS clock:: |
| 69 | |
| 70 | ioctl(d, RTC_SET_TIME, &rtc); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 71 | |
| 72 | The rtc is a pointer to a data structure defined in rtc.h which is close |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 73 | to a struct tm:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 74 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 75 | struct rtc_time { |
| 76 | int tm_sec; |
| 77 | int tm_min; |
| 78 | int tm_hour; |
| 79 | int tm_mday; |
| 80 | int tm_mon; |
| 81 | int tm_year; |
| 82 | int tm_wday; |
| 83 | int tm_yday; |
| 84 | int tm_isdst; |
| 85 | }; |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 86 | |
| 87 | The driver takes care of converting back an forth between the EFI time and |
| 88 | this format. |
| 89 | |
| 90 | Those two ioctl()s can be exercised with the hwclock command: |
| 91 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 92 | For reading:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 93 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 94 | # /sbin/hwclock --show |
| 95 | Mon Mar 6 15:32:32 2000 -0.910248 seconds |
| 96 | |
| 97 | For setting:: |
| 98 | |
| 99 | # /sbin/hwclock --systohc |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 100 | |
| 101 | Root privileges are required to be able to set the time of day. |
| 102 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 103 | 4. Wakeup Alarm service |
| 104 | ======================= |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 105 | |
| 106 | EFI provides an API by which one can program when a machine should wakeup, |
| 107 | i.e. reboot. This is very different from the alarm provided by the legacy |
| 108 | RTC which is some kind of interval timer alarm. For this reason we don't use |
| 109 | the same ioctl()s to get access to the service. Instead we have |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 110 | introduced 2 news ioctl()s to the interface of an RTC. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 111 | |
| 112 | We have added 2 new ioctl()s that are specific to the EFI driver: |
| 113 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 114 | Read the current state of the alarm:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 115 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 116 | ioctl(d, RTC_WKLAM_RD, &wkt) |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 117 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 118 | Set the alarm or change its status:: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 119 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 120 | ioctl(d, RTC_WKALM_SET, &wkt) |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 121 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 122 | The wkt structure encapsulates a struct rtc_time + 2 extra fields to get |
| 123 | status information:: |
| 124 | |
| 125 | struct rtc_wkalrm { |
| 126 | |
| 127 | unsigned char enabled; /* =1 if alarm is enabled */ |
| 128 | unsigned char pending; /* =1 if alarm is pending */ |
| 129 | |
| 130 | struct rtc_time time; |
| 131 | } |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 132 | |
| 133 | As of today, none of the existing user-level apps supports this feature. |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 134 | However writing such a program should be hard by simply using those two |
| 135 | ioctl(). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 136 | |
| 137 | Root privileges are required to be able to set the alarm. |
| 138 | |
Mauro Carvalho Chehab | db9a097 | 2019-04-18 10:10:33 -0300 | [diff] [blame] | 139 | 5. References |
| 140 | ============= |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 141 | |
| 142 | Checkout the following Web site for more information on EFI: |
| 143 | |
| 144 | http://developer.intel.com/technology/efi/ |