rtc(4) Device Drivers Manual rtc(4) BEZEICHNUNG rtc - Echtzeituhr UBERSICHT #include int ioctl(fd, RTC_request, param); BESCHREIBUNG Dies ist die Schnittstelle zu Treibern fur Echtzeit-Uhren (RTCs). Die meisten Computer verfugen uber eine oder mehrere Hardware-Uhren, die die aktuelle >>Wanduhr<<-Zeit erfassen. Diese werden als >>Real Time Clocks<< (RTC) bezeichnet. Eine von ihnen ist in der Regel batteriegepuffert, sodass sie die Zeit verfolgt, auch wahrend der Computer ausgeschaltet ist. RTCs stellen oft Alarme und andere Interrupts bereit. In allen i386-PCs und ACPI-basierten Systemen ist eine RTC eingebaut, die kompatibel zum Chip aus dem Originalen PC/AT ist, dem Motorola MC146818. Heutzutage ist solch eine RTC im Allgemeinen in den Chipsatz des Mainboards (South Bridge) integriert und nutzt eine austauschbare munzgrosse Batterie. Nicht-PC-Systeme wie beispielsweise eingebettete Systeme, die um >>System-on-chip<<-Prozessoren aufgebaut sind, nutzen andere Implementierungen. Ublicherweise bieten sie nicht die gleiche Funktionalitat wie die RTC aus einem PC/AT. RTC im Vergleich zur Systemuhr RTCs sollten nicht mit der Systemuhr verwechselt werden. Diese ist eine Software-Uhr, die vom Kernel gepflegt wird. Er verwendet sie fur die Implementierung von gettimeofday(2) und time(2) sowie fur die Zeitstempel von Dateien usw. Die Systemuhr zahlt Sekunden und Mikrosekunden seit einem Startpunkt, der als die >>POSIX Epoch<< (1970-01-01 00:00:00 +0000 (UTC)) definiert ist. (Eine verbreitete Umsetzung zahlt Timer-Interrupts, einmal pro >>Jiffy<<, bei einer Frequenz von 100, 250 oder 1000 Hz). Das heisst, sie sollte die >>Wanduhr<<-Zeit angeben, wie es auch RTCS tun. Ein wesentlicher Unterschied zwischen einer RTC und der Systemuhr ist, dass RTCs auch dann laufen, wenn sich das System in einem Zustand niedrigen Energieverbrauchs (einschliesslich >>ausgeschaltet<<) befindet, und die Systemuhr das nicht kann. Bis sie initialisiert wird, kann die Systemuhr nur die Zeit seit Systemstart berichten und nicht seit der POSIX-Epoche. Also wird beim Booten und nach der Ruckkehr aus einem Niedrigenergie-Zustand des Systems die Systemuhr oft uber eine RTC auf die aktuelle Wanduhr-Zeit gesetzt werden. Systeme ohne eine RTC mussen die Systemuhr mit einer anderen Uhr stellen, vielleicht uber das Netzwerk oder durch die manuelle Eingabe der Daten. RTC-Funktionen RTCs konnen direkt mit den im Folgenden aufgefuhrten ioctl(2)-Aufrufen und mittels hwclock(8) gelesen und geschrieben werden. Neben der Verfolgung von Zeit und Datum konnen viele RTCs Interrupts erzeugen o bei jeder Aktualisierung der Uhr (d.h. einmal pro Sekunde); o in periodischen Abstanden mit einer Frequenz, die ein Mehrfaches einer beliebigen Zweierpotenz im Bereich zwischen 2 Hz und 8192 Hz ist; o bei Erreichen einer vorher festgelegten Alarmzeit. Jede dieser Interruptquellen kann separat aktiviert oder deaktiviert werden. Auf vielen Systemen kann ein solch ein Interrupt als ein Ereignis zum >>Wecken<< aus einem Energiesparzustand wie Suspend-to-RAM (STR, auf ACPI-Systemen S3 genannt), Hibernation (S4 auf ACPI-Systemen) oder sogar >>aus<< (S5) konfiguriert werden. Auf manchen Systemen kann nicht die batteriegepufferte RTC Interrupts auslosen, sondern eine andere. Das Gerat /dev/rtc (oder /dev/rtc0, /dev/rtc1 usw.) kann nur einmal (bis es wieder geschlossen wird) und nur fur einen Lesezugriff geoffnet werden. Beim Aufruf von read(2) und select(2) wird der aufrufende Prozess blockiert, bis er den nachsten Interrupt von dieser RTC empfangt. Im Anschluss an den Interrupt kann der Prozess einen >>long integer<< auslesen. Dessen niedrigstwertiges Byte enthalt eine Bitmaske, die die Typen der aufgetretenen Interrupts codiert, wahrend die verbleibenden 3 Bytes die Anzahl von Interrupts seit dem letzten read(2) enthalten. ioctl(2)-Schnittstelle Die folgenden ioctl(2)-Anfragen sind fur mit RTC-Geraten verbundene Dateideskriptoren definiert: RTC_RD_TIME gibt die Zeit der RTC in der folgenden Struktur zuruck: struct rtc_time { int tm_sec; int tm_min; int tm_hour; int tm_mday; int tm_mon; int tm_year; int tm_wday; /* nicht verwendet */ int tm_yday; /* nicht verwendet */ int tm_isdst; /* nicht verwendet */ }; Die Felder dieser Struktur haben die gleiche Bedeutung und die gleichen Wertebereiche wie die in gmtime(3) beschriebene Strukur tm. Als drittes Argument von ioctl(2) sollte ein Zeiger auf diese Strukur ubergeben werden. RTC_SET_TIME setzt die Zeit der RTC auf die in der rtc_time-Struktur festgelegte Zeit, auf die das dritte ioctl(2)-Argument zeigt. Zum Setzen der Zeit muss der Prozess privilegiert sein (d.h. uber die Capability CAP_SYS_TIME verfugen). RTC_ALM_READ RTC_ALM_SET liest und setzt die Alarmzeit bei RTCs, die Alarme unterstutzen. Der Interrupt fur den Alarm muss separat mit den Anfragen RTC_AIE_ON und RTC_AIE_OFF aktiviert oder deaktiviert werden. Das dritte Argument fur ioctl(2) ist ein Zeiger auf eine rtc_time-Struktur. Von der Struktur werden lediglich die Felder tm_sec, tm_min und tm_hour ausgewertet. RTC_IRQP_READ RTC_IRQP_SET liest und setzt die Frequenz periodischer Interrupts bei RTCs, die periodische Interrupts unterstutzen. Der periodische Interrupt muss separat mit den Anfragen RTC_PIE_ON und RTC_PIE_OFF aktiviert oder deaktiviert werden. Das dritte Argument von ioctl(2) ist ein unsigned long * beziehungsweise ein unsigned long. Der Wert ist die Anzahl der Interrupts pro Sekunde. Der Satz von zulassigen Frequenzen besteht aus Vielfachen von zwei aus dem Bereich von 2 bis 8192. Nur ein privilegierter Prozess (d.h. einer mit der CAP_SYS_RESOURCE-Capability) kann Frequenzen uber dem in /proc/sys/dev/rtc/max-user-freq festgelegten Wert festlegen. (Diese Datei enthalt standardmassig den Wert 64.) RTC_AIE_ON RTC_AIE_OFF aktiviert oder deaktiviert den Alarm-Interrupt fur RTCs, die Alarme unterstutzen. Das dritte Argument von ioctl(2) wird ignoriert. RTC_UIE_ON RTC_UIE_OFF aktiviert oder deaktiviert den Interrupt bei jeder Aktualisierung der Uhr fur RTCs, die diesen >>einmal pro Sekunde<<-Interrupt unterstutzen. Das dritte Argument von ioctl(2) wird ignoriert. RTC_PIE_ON RTC_PIE_OFF aktiviert oder deaktiviert den periodischen Interrupt fur RTCs, die diese periodischen Interrupts unterstutzen. Das dritte Argument von ioctl(2) wird ignoriert. Nur ein privilegierter Prozess (d.h. einer mit der CAP_SYS_RESOURCE-Capability) kann den periodischen Interrupt aktivieren, wenn die Frequenz uber dem in /proc/sys/dev/rtc/max-user-freq festgelegten Wert liegt. RTC_EPOCH_READ RTC_EPOCH_SET Viele RTCs codieren das Jahr in einem 8-Bit-Register, das entweder als 8-Bit-Binarzahl oder als BCD-Zahl interpretiert wird. In beiden Fallen wird die Zahl relativ zum zeitlichen Bezugspunkt (Epoch) dieser RTC interpretiert. Auf den meisten Systemen ist dies das Jahr 1900, aber auf Alpha und MIPS konnte es abhangig vom RTC-Register fur das Jahr auch 1952, 1980 oder 2000 sein. Bei einigen RTCs kann mit diesen Operationen das Bezugsjahr gelesen bzw. gesetzt werden. Das dritte Argument von ioctl(2) ist ein unsigned long * oder ein unsigned long und entsprechend ist der zuruckgegebene (oder zugewiesene Wert) das Bezugsjahr. Um das Bezugsjahr der RTC zu setzen, muss der Prozess privilegiert sein (d.h. uber die Capability CAP_SYS_TIME verfugen). RTC_WKALM_RD RTC_WKALM_SET Einige RTCs unterstutzen eine leistungsfahigere Alarm-Schnittstelle mittels dieser >>ioctls<< zum Schreiben oder Lesen der Alarmzeit der RTC mit dieser Struktur: struct rtc_wkalrm { unsigned char enabled; unsigned char pending; struct rtc_time time; }; Der Schalter enabled wird zur Aktivierung oder Deaktivierung des Alarm-Interrupts oder zur Ermittlung seines aktuellen Status verwendet; wenn Sie diese Aufrufe einsetzen, werden RTC_AIE_ON und RTC_AIE_OFF nicht beachtet. Der Schalter pending wird von RTC_WKALM_RD verwendet, um einen anstehenden Interrupt anzuzeigen. (Er ist also unter Linux meist nutzlos - es sei denn, es wird mit durch EFI-Firmware verwalteteten RTCs kommuniziert.) Das Feld time wird mit RTC_ALM_READ und RTC_ALM_SET verwendet, mit dem Unterschied, dass die Felder tm_mday, tm_mon und tm_year ebenfalls gultig sind. Ein Zeiger auf diese Struktur sollte als drittes Argument an ioctl(2) ubergeben werden. DATEIEN /dev/rtc /dev/rtc0 /dev/rtc1 (zeichenorientierte) RTC-Geratedateien. /proc/driver/rtc Status der (ersten) RTC. ANMERKUNGEN Wenn die Systemzeit des Kernels mittels adjtimex(2) mit einer externen Referenz synchronisiert wird, wird er eine bestimmte RTC periodisch alle 11 Minuten aktualisieren. Dafur muss der Kernel kurzzeitig periodische Interrupts ausschalten. Dadurch konnten Programme beeintrachtigt werden, die diese RTC verwenden. Der Zeitbezugspunkt (Epoch) hat nichts mit der POSIX Epoch zu tun, die lediglich fur die Systemuhr verwendet wird. Wenn das Jahr entsprechend der RTC-Epoch und dem Jahres-Register kleiner als 1970 ist, werden 100 Jahre drauf geschlagen, also ein Jahr zwischen 2000 und 2069 angenommen. Einige RTCs unterstutzen Platzhalterwerte (wildcards) in den Alarm-Feldern, um Szenarien wie regelmassige Alarme 15 Minuten nach jeder vollen Stunde oder am ersten Tag eines jeden Monats zu unterstutzen. Die Verwendung ist nicht portabel; portabler User-Space-Code erwartet lediglich einen einzelnen Alarm-Interrupt und wird den Alarm bei Erhalt entweder deaktivieren oder neu initialisieren. Einige RTCs unterstutzen periodische Interrupts mit Zeiten, die ein Vielfaches einer Sekunde anstatt Bruchteile einer Sekunde sind; mehrere Alarme, programmierbare Ausgangs-Taktsignale; nichtfluchtigen Speicher und weitere Fahigkeiten, die derzeit nicht von dieser API zuganglich gemacht werden. SIEHE AUCH date(1), adjtimex(2), gettimeofday(2), settimeofday(2), stime(2), time(2), gmtime(3), time(7), hwclock(8) Documentation/rtc.txt im Linux-Kernelquelltext-Verzeichnis UBERSETZUNG Die deutsche Ubersetzung dieser Handbuchseite wurde von Martin Eberhard Schauer erstellt. Diese Ubersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezuglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG ubernommen. Wenn Sie Fehler in der Ubersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Ubersetzer . Linux man-pages 6.06 31. Oktober 2023 rtc(4)