PageRenderTime 9ms CodeModel.GetById 2ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 1ms

/Documentation/ia64/efirtc.txt

https://bitbucket.org/evzijst/gittest
Plain Text | 128 lines | 91 code | 37 blank | 0 comment | 0 complexity | fef081a861b13f453d85d65ddf9f3c68 MD5 | raw file
  1EFI Real Time Clock driver
  2-------------------------------
  3S. Eranian <eranian@hpl.hp.com>
  4March 2000
  5
  6I/ Introduction
  7
  8This document describes the efirtc.c driver has provided for
  9the IA-64 platform. 
 10
 11The purpose of this driver is to supply an API for kernel and user applications
 12to get access to the Time Service offered by EFI version 0.92.
 13
 14EFI provides 4 calls one can make once the OS is booted: GetTime(),
 15SetTime(), GetWakeupTime(), SetWakeupTime() which are all supported by this
 16driver. We describe those calls as well the design of the driver in the
 17following sections.
 18
 19II/ Design Decisions
 20
 21The original ideas was to provide a very simple driver to get access to, 
 22at first, the time of day service. This is required in order to access, in a 
 23portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock 
 24to initialize the system view of the time during boot.
 25
 26Because we wanted to minimize the impact on existing user-level apps using
 27the CMOS clock, we decided to expose an API that was very similar to the one
 28used today with the legacy RTC driver (driver/char/rtc.c). However, because 
 29EFI provides a simpler services, not all all ioctl() are available. Also
 30new ioctl()s have been introduced for things that EFI provides but not the 
 31legacy.
 32
 33EFI uses a slightly different way of representing the time, noticeably
 34the reference date is different. Year is the using the full 4-digit format.
 35The Epoch is January 1st 1998. For backward compatibility reasons we don't
 36expose this new way of representing time. Instead we use something very 
 37similar to the struct tm, i.e. struct rtc_time, as used by hwclock.
 38One of the reasons for doing it this way is to allow for EFI to still evolve
 39without necessarily impacting any of the user applications. The decoupling
 40enables flexibility and permits writing wrapper code is ncase things change.
 41
 42The driver exposes two interfaces, one via the device file and a set of
 43ioctl()s. The other is read-only via the /proc filesystem. 
 44
 45As of today we don't offer a /proc/sys interface.
 46
 47To allow for a uniform interface between the legacy RTC and EFI time service,
 48we 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 
 50in include/linux/mc146818rtc.h.
 51
 52 
 53III/ Time of day service
 54
 55The part of the driver gives access to the time of day service of EFI.
 56Two 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
 62The rtc is a pointer to a data structure defined in rtc.h which is close
 63to a struct tm:
 64
 65struct 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
 77The driver takes care of converting back an forth between the EFI time and
 78this format.
 79
 80Those two ioctl()s can be exercised with the hwclock command:
 81
 82For reading:
 83# /sbin/hwclock --show
 84Mon Mar  6 15:32:32 2000  -0.910248 seconds
 85
 86For setting:
 87# /sbin/hwclock --systohc
 88
 89Root privileges are required to be able to set the time of day.
 90
 91IV/ Wakeup Alarm service
 92
 93EFI provides an API by which one can program when a machine should wakeup,
 94i.e. reboot. This is very different from the alarm provided by the legacy
 95RTC which is some kind of interval timer alarm. For this reason we don't use
 96the same ioctl()s to get access to the service. Instead we have
 97introduced 2 news ioctl()s to the interface of an RTC. 
 98
 99We 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
107The wkt structure encapsulates a struct rtc_time + 2 extra fields to get 
108status information:
109	
110struct 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
118As of today, none of the existing user-level apps supports this feature.
119However writing such a program should be hard by simply using those two 
120ioctl(). 
121
122Root privileges are required to be able to set the alarm.
123
124V/ References.
125
126Checkout the following Web site for more information on EFI:
127
128http://developer.intel.com/technology/efi/