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