efirtc.rst (4550B)
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/