About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / ia64 / efirtc.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:39 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.