Documentation/ia64/efirtc.rst

   1 ==========================
   2 EFI Real Time Clock driver
   3 ==========================
   4
   5 S. Eranian <eranian@hpl.hp.com>
   6
   7 March 2000
   8
   9 1. Introduction
  10 ===============
  11
  12 This document describes the efirtc.c driver has provided for
  13 the IA-64 platform.
  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
  23 2. Design Decisions
  24 ===================
  25
  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
  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
  33 used today with the legacy RTC driver (driver/char/rtc.c). However, because
  34 EFI provides a simpler services, not all ioctl() are available. Also
  35 new ioctl()s have been introduced for things that EFI provides but not the
  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
  41 expose this new way of representing time. Instead we use something very
  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
  48 ioctl()s. The other is read-only via the /proc filesystem.
  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,
  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
  55 in include/linux/mc146818rtc.h.
  56
  57
  58 3. Time of day service
  59 ======================
  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
  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
  72 The rtc is a pointer to a data structure defined in rtc.h which is close
  73 to 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
  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
  92 For reading::
  93
  94         # /sbin/hwclock --show
  95         Mon Mar  6 15:32:32 2000  -0.910248 seconds
  96
  97 For setting::
  98
  99         # /sbin/hwclock --systohc
 100
 101 Root privileges are required to be able to set the time of day.
 102
 103 4. Wakeup Alarm service
 104 =======================
 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
 110 introduced 2 news ioctl()s to the interface of an RTC.
 111
 112 We 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
 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   }
 132
 133 As of today, none of the existing user-level apps supports this feature.
 134 However writing such a program should be hard by simply using those two
 135 ioctl().
 136
 137 Root privileges are required to be able to set the alarm.
 138
 139 5. References
 140 =============
 141
 142 Checkout the following Web site for more information on EFI:
 143
 144 http://developer.intel.com/technology/efi/