blob: 2f7ff5026308b8bc686bcb8502f8f8a395d28fb0 [file] [log] [blame]
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -03001==========================
Linus Torvalds1da177e2005-04-16 15:20:36 -07002EFI Real Time Clock driver
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -03003==========================
4
Linus Torvalds1da177e2005-04-16 15:20:36 -07005S. Eranian <eranian@hpl.hp.com>
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -03006
Linus Torvalds1da177e2005-04-16 15:20:36 -07007March 2000
8
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030091. Introduction
10===============
Linus Torvalds1da177e2005-04-16 15:20:36 -070011
12This document describes the efirtc.c driver has provided for
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030013the IA-64 platform.
Linus Torvalds1da177e2005-04-16 15:20:36 -070014
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
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -0300232. Design Decisions
24===================
Linus Torvalds1da177e2005-04-16 15:20:36 -070025
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030026The 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
Linus Torvalds1da177e2005-04-16 15:20:36 -070029to 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
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030033used today with the legacy RTC driver (driver/char/rtc.c). However, because
Paolo Ornati670e9f32006-10-03 22:57:56 +020034EFI provides a simpler services, not all ioctl() are available. Also
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030035new ioctl()s have been introduced for things that EFI provides but not the
Linus Torvalds1da177e2005-04-16 15:20:36 -070036legacy.
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
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030041expose this new way of representing time. Instead we use something very
Linus Torvalds1da177e2005-04-16 15:20:36 -070042similar 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
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030048ioctl()s. The other is read-only via the /proc filesystem.
Linus Torvalds1da177e2005-04-16 15:20:36 -070049
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,
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030053we 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
Linus Torvalds1da177e2005-04-16 15:20:36 -070055in include/linux/mc146818rtc.h.
56
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030057
583. Time of day service
59======================
Linus Torvalds1da177e2005-04-16 15:20:36 -070060
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
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030064 Read the CMOS clock::
Linus Torvalds1da177e2005-04-16 15:20:36 -070065
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030066 ioctl(d, RTC_RD_TIME, &rtc);
67
68 Write the CMOS clock::
69
70 ioctl(d, RTC_SET_TIME, &rtc);
Linus Torvalds1da177e2005-04-16 15:20:36 -070071
72The rtc is a pointer to a data structure defined in rtc.h which is close
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030073to a struct tm::
Linus Torvalds1da177e2005-04-16 15:20:36 -070074
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030075 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 };
Linus Torvalds1da177e2005-04-16 15:20:36 -070086
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
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030092For reading::
Linus Torvalds1da177e2005-04-16 15:20:36 -070093
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -030094 # /sbin/hwclock --show
95 Mon Mar 6 15:32:32 2000 -0.910248 seconds
96
97For setting::
98
99 # /sbin/hwclock --systohc
Linus Torvalds1da177e2005-04-16 15:20:36 -0700100
101Root privileges are required to be able to set the time of day.
102
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -03001034. Wakeup Alarm service
104=======================
Linus Torvalds1da177e2005-04-16 15:20:36 -0700105
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
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -0300110introduced 2 news ioctl()s to the interface of an RTC.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700111
112We have added 2 new ioctl()s that are specific to the EFI driver:
113
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -0300114 Read the current state of the alarm::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700115
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -0300116 ioctl(d, RTC_WKLAM_RD, &wkt)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700117
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -0300118 Set the alarm or change its status::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700119
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -0300120 ioctl(d, RTC_WKALM_SET, &wkt)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700121
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -0300122The 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 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700132
133As of today, none of the existing user-level apps supports this feature.
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -0300134However writing such a program should be hard by simply using those two
135ioctl().
Linus Torvalds1da177e2005-04-16 15:20:36 -0700136
137Root privileges are required to be able to set the alarm.
138
Mauro Carvalho Chehabdb9a0972019-04-18 10:10:33 -03001395. References
140=============
Linus Torvalds1da177e2005-04-16 15:20:36 -0700141
142Checkout the following Web site for more information on EFI:
143
144http://developer.intel.com/technology/efi/