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