[linux-2.6-block.git] / Documentation / ia64 / efirtc.rst

==========================
EFI Real Time Clock driver
==========================

S. Eranian <eranian@hpl.hp.com>

March 2000

1. Introduction
===============

This document describes the efirtc.c driver has provided for
the IA-64 platform.

The purpose of this driver is to supply an API for kernel and user applications
to get access to the Time Service offered by EFI version 0.92.

EFI provides 4 calls one can make once the OS is booted: GetTime(),
SetTime(), GetWakeupTime(), SetWakeupTime() which are all supported by this
driver. We describe those calls as well the design of the driver in the
following sections.

2. Design Decisions
===================

The original ideas was to provide a very simple driver to get access to,
at first, the time of day service. This is required in order to access, in a
portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock
to initialize the system view of the time during boot.

Because we wanted to minimize the impact on existing user-level apps using
the CMOS clock, we decided to expose an API that was very similar to the one
used today with the legacy RTC driver (driver/char/rtc.c). However, because
EFI provides a simpler services, not all ioctl() are available. Also
new ioctl()s have been introduced for things that EFI provides but not the
legacy.

EFI uses a slightly different way of representing the time, noticeably
the reference date is different. Year is the using the full 4-digit format.
The Epoch is January 1st 1998. For backward compatibility reasons we don't
expose this new way of representing time. Instead we use something very
similar to the struct tm, i.e. struct rtc_time, as used by hwclock.
One of the reasons for doing it this way is to allow for EFI to still evolve
without necessarily impacting any of the user applications. The decoupling
enables flexibility and permits writing wrapper code is ncase things change.

The driver exposes two interfaces, one via the device file and a set of
ioctl()s. The other is read-only via the /proc filesystem.

As of today we don't offer a /proc/sys interface.

To allow for a uniform interface between the legacy RTC and EFI time service,
we have created the include/linux/rtc.h header file to contain only the
"public" API of the two drivers.  The specifics of the legacy RTC are still
in include/linux/mc146818rtc.h.


3. Time of day service
======================

The part of the driver gives access to the time of day service of EFI.
Two ioctl()s, compatible with the legacy RTC calls:

	Read the CMOS clock::

		ioctl(d, RTC_RD_TIME, &rtc);

	Write the CMOS clock::

		ioctl(d, RTC_SET_TIME, &rtc);

The rtc is a pointer to a data structure defined in rtc.h which is close
to a struct tm::

  struct rtc_time {
          int tm_sec;
          int tm_min;
          int tm_hour;
          int tm_mday;
          int tm_mon;
          int tm_year;
          int tm_wday;
          int tm_yday;
          int tm_isdst;
  };

The driver takes care of converting back an forth between the EFI time and
this format.

Those two ioctl()s can be exercised with the hwclock command:

For reading::

	# /sbin/hwclock --show
	Mon Mar  6 15:32:32 2000  -0.910248 seconds

For setting::

	# /sbin/hwclock --systohc

Root privileges are required to be able to set the time of day.

4. Wakeup Alarm service
=======================

EFI provides an API by which one can program when a machine should wakeup,
i.e. reboot. This is very different from the alarm provided by the legacy
RTC which is some kind of interval timer alarm. For this reason we don't use
the same ioctl()s to get access to the service. Instead we have
introduced 2 news ioctl()s to the interface of an RTC.

We have added 2 new ioctl()s that are specific to the EFI driver:

	Read the current state of the alarm::

		ioctl(d, RTC_WKLAM_RD, &wkt)

	Set the alarm or change its status::

		ioctl(d, RTC_WKALM_SET, &wkt)

The wkt structure encapsulates a struct rtc_time + 2 extra fields to get
status information::

  struct rtc_wkalrm {

          unsigned char enabled; /* =1 if alarm is enabled */
          unsigned char pending; /* =1 if alarm is pending  */

          struct rtc_time time;
  }

As of today, none of the existing user-level apps supports this feature.
However writing such a program should be hard by simply using those two
ioctl().

Root privileges are required to be able to set the alarm.

5. References
=============

Checkout the following Web site for more information on EFI:

http://developer.intel.com/technology/efi/
Commit	Line	Data
db9a0975	1	==========================
1da177e4	2	EFI Real Time Clock driver
db9a0975 MCC	3	==========================
db9a0975 MCC	4
1da177e4	5	S. Eranian <eranian@hpl.hp.com>
db9a0975	6
1da177e4 LT	7	March 2000
1da177e4 LT	8
db9a0975 MCC	9	1. Introduction
db9a0975 MCC	10	===============
1da177e4 LT	11
1da177e4 LT	12	This document describes the efirtc.c driver has provided for
db9a0975	13	the IA-64 platform.
1da177e4 LT	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
db9a0975 MCC	23	2. Design Decisions
db9a0975 MCC	24	===================
1da177e4	25
db9a0975 MCC	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
1da177e4 LT	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
db9a0975	33	used today with the legacy RTC driver (driver/char/rtc.c). However, because
670e9f34	34	EFI provides a simpler services, not all ioctl() are available. Also
db9a0975	35	new ioctl()s have been introduced for things that EFI provides but not the
1da177e4 LT	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
db9a0975	41	expose this new way of representing time. Instead we use something very
1da177e4 LT	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
db9a0975	48	ioctl()s. The other is read-only via the /proc filesystem.
1da177e4 LT	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,
db9a0975 MCC	53	we have created the include/linux/rtc.h header file to contain only the
db9a0975 MCC	54	"public" API of the two drivers. The specifics of the legacy RTC are still
1da177e4 LT	55	in include/linux/mc146818rtc.h.
1da177e4 LT	56
db9a0975 MCC	57
	58	3. Time of day service
	59	======================
1da177e4 LT	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
db9a0975 MCC	64	Read the CMOS clock::
	65
	66	ioctl(d, RTC_RD_TIME, &rtc);
	67
	68	Write the CMOS clock::
1da177e4	69
db9a0975	70	ioctl(d, RTC_SET_TIME, &rtc);
1da177e4 LT	71
1da177e4 LT	72	The rtc is a pointer to a data structure defined in rtc.h which is close
db9a0975 MCC	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	};
1da177e4 LT	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
db9a0975	92	For reading::
1da177e4	93
db9a0975 MCC	94	# /sbin/hwclock --show
	95	Mon Mar 6 15:32:32 2000 -0.910248 seconds
	96
	97	For setting::
	98
	99	# /sbin/hwclock --systohc
1da177e4 LT	100
	101	Root privileges are required to be able to set the time of day.
	102
db9a0975 MCC	103	4. Wakeup Alarm service
db9a0975 MCC	104	=======================
1da177e4 LT	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
db9a0975	110	introduced 2 news ioctl()s to the interface of an RTC.
1da177e4 LT	111
	112	We have added 2 new ioctl()s that are specific to the EFI driver:
	113
db9a0975 MCC	114	Read the current state of the alarm::
	115
	116	ioctl(d, RTC_WKLAM_RD, &wkt)
	117
	118	Set the alarm or change its status::
	119
	120	ioctl(d, RTC_WKALM_SET, &wkt)
1da177e4	121
db9a0975 MCC	122	The wkt structure encapsulates a struct rtc_time + 2 extra fields to get
db9a0975 MCC	123	status information::
1da177e4	124
db9a0975	125	struct rtc_wkalrm {
1da177e4	126
db9a0975 MCC	127	unsigned char enabled; /* =1 if alarm is enabled */
db9a0975 MCC	128	unsigned char pending; /* =1 if alarm is pending */
1da177e4	129
db9a0975 MCC	130	struct rtc_time time;
db9a0975 MCC	131	}
1da177e4 LT	132
1da177e4 LT	133	As of today, none of the existing user-level apps supports this feature.
db9a0975 MCC	134	However writing such a program should be hard by simply using those two
db9a0975 MCC	135	ioctl().
1da177e4 LT	136
	137	Root privileges are required to be able to set the alarm.
	138
db9a0975 MCC	139	5. References
db9a0975 MCC	140	=============
1da177e4 LT	141
	142	Checkout the following Web site for more information on EFI:
	143
	144	http://developer.intel.com/technology/efi/