NOM
rtc - Horloge temps réel
SYNOPSIS
#include <linux/rtc.h>
int ioctl(fd, RTC_request, param);
Il s’agit d’une interface aux pilotes pour les horloges temps réel
(RTC).
La plupart des ordinateurs disposent d’une ou plusieurs horloges
matérielles intégrées, enregistrant l’heure locale. Elles sont appelées
« horloges temps réel » (RTC). L’une d’entre elles est généralement
alimentée par une pile afin de rester à l’heure une fois l’ordinateur
éteint. Les RTC permettent souvent d’utiliser des alarmes et d’autres
interruptions.
Tous les PC i386 et les systèmes basés sur ACPI ont une RTC compatible
avec la puce Motorola MC146818 du PC/AT d’origine. Aujourd’hui
l’horloge est généralement intégrée au jeu de composants de la carte
mère (« south bridge ») et utilise une pile de secours remplaçable de
la taille d’une pièce de monnaie.
Les systèmes autres que les PC, comme les systèmes embarqués construits
autour de processeurs embarquant tout le système, utilisent d’autres
mises en oeuvre. Généralement, ils n’offrent pas les mêmes
fonctionnalités qu’une RTC de PC/AT.
RTC vs horloge système
Les RTC ne doivent pas être confondues avec l’horloge système, qui est
une horloge logicielle gérée par le noyau et utilisée dans
gettimeofday(2) et time(2), ainsi que pour le marquage temporel des
fichiers, etc. L’horloge système indique le nombre de secondes et
microsecondes écoulées depuis un instant de départ, défini comme étant
le « POSIX Epoch » : 1er janvier 1970 à 0h00 UTC. (Une mise en oeuvre
usuelle compte le nombre d’interruptions, une par pulsation à une
fréquence de 100, 250 ou 1000 Hz.) C’est-à-dire qu’elle est supposée
renvoyer l’heure locale, comme le font les RTC.
Une différence clé entre une RTC et l’horloge système est qu’une RTC
fonctionne même lorsque le système est dans un état de veille
d’alimentation (incluant « éteint ») et que l’horloge système ne peut
fonctionner. Jusqu’à son initialisation, l’horloge système ne peut
indiquer que le temps écoulé depuis le démarrage du système mais pas
celui depuis le « POSIX Epoch ». Ainsi, au démarrage et après la sortie
de veille, l’horloge système sera souvent réglée à l’heure locale
actuelle en utilisant une RTC. Les systèmes sans RTC ont besoin de
régler leur horloge système par un autre moyen, peut-être à travers le
réseau ou en entrant les valeurs à la main.
Fonctionnalités d’une RTC
Les RTC peuvent être lues et réglées avec hwclock(8), ou directement en
utilisant les ioctl listés ci-dessous.
En plus du compte de la date et de l’heure, de nombreuses RTC peuvent
aussi générer des interruptions :
* à chaque mise à jour de l’horloge (c.-à-d.. une fois par seconde) ;
* à des intervalles réguliers, de fréquence réglable à une puissance
de 2 entre 2 Hz et 8192 Hz ;
* lorsque la date d’une alarme réglée auparavant est atteinte.
Chacune de ces sources d’interruptions peut être activée ou désactivée
séparément. Sur de nombreux systèmes, l’interruption venant de l’alarme
peut être configurée comme un événement déclenchant le réveil du
système, et ainsi sortir le système d’un état de veille d’alimentation
comme la veille en RAM (STR, appelée S3 dans les systèmes ACPI),
l’hibernation (appelée S4 dans les systèmes ACPI) ou même l’extinction
(appelée S5 dans les systèmes ACPI). Sur certains systèmes, la pile de
secours de la RTC ne peut générer d’interruptions, alors qu’une autre
le peut.
Le périphérique /dev/rtc (ou /dev/rtc0, /dev/rtc1, etc.) est en lecture
seule et un seul accès simultané est possible. Un processus appelant
read(2) ou select(2) est bloqué jusqu’à la réception de l’interruption
RTC suivante. Suite à l’interruption, le processus peut lire un entier
long, dont l’octet de poids faible contient le type d’interruption qui
vient de se produire et les 3 octets restants contiennent le nombre
d’interruptions depuis le dernier appel à read(2).
Interface ioctl(2)
Les appels ioctl(2) suivants sont définis sur les descripteurs des
fichiers associés aux périphériques RTC :
RTC_RD_TIME
Renvoie l’heure de cette RTC dans la structure suivante :
struct rtc_time {
int tm_sec;
int tm_min;
int tm_hour;
int tm_mday;
int tm_mon;
int tm_year;
int tm_wday; /* non utilisé */
int tm_yday; /* non utilisé */
int tm_isdst; /* non utilisé */
};
Les membres de cette structure ont les mêmes sens et les mêmes
portées que la ceux de la structure tm décrite dans gmtime(3).
Un pointeur vers cette structure est attendu en troisième
paramètre pour ioctl(2).
RTC_SET_TIME
Règle cette horloge RTC à l’heure spécifiée par la structure
rtc_time vers laquelle pointe le troisième paramètre passé à
ioctl(2). Pour pouvoir modifier l’heure RTC, le processus doit
être privilégié (i.e. disposer du droit CAP_SYS_TIME).
RTC_ALM_READ, RTC_ALM_SET
Lit et règle l’heure d’alarme, pour les horloges RTC qui gèrent
les alarmes. L’interruption venant de l’alarme doit être activée
ou désactivée séparément en utilisant respectivement les
requêtes RTC_AIE_ON ou RTC_AIE_OFF. Le troisième paramètre
d’ioctl(2) est un pointeur vers une structure rtc_time. Seuls
les champs tm_sec, tm_min, et tm_hour de cette structure sont
utilisés.
RTC_IRQP_READ, RTC_IRQP_SET
Lit et règle la fréquence des interruptions, pour les horloges
RTC gérant les interruptions périodiques. L’interruption
périodique doit être activée ou désactivée séparément en
utilisant respectivement les requêtes RTC_PIE_ON ou RTC_PIE_OFF.
Le troisième paramètre d’ioctl(2) est un unsigned long * ou un
unsigned long respectivement. La valeur représente la fréquence
en interruptions par seconde. Le jeu des fréquences permises est
l’ensemble des multiples de deux entre 2 et 8192. Seul un
processus privilégié (i.e. disposant du droit CAP_SYS_RESOURCE)
peut régler une fréquence supérieure à celle spécifiée dans
/proc/sys/dev/rtc/max-user-freq, par défaut 64.
RTC_AIE_ON, RTC_AIE_OFF
Active ou désactive l’interruption venant de l’alarme, pour les
RTC qui gèrent les alarmes. Le troisième paramètre d’ioctl(2)
est ignoré.
RTC_UIE_ON, RTC_UIE_OFF
Active ou désactive l’interruption à chaque mise à jour, pour
les horloges gérant cette interruption envoyée chaque seconde.
Le troisième paramètre d’ioctl(2) est ignoré.
RTC_PIE_ON, RTC_PIE_OFF
Active ou désactive l’interruption périodique, pour les RTC
gérant ces interruptions périodiques. Le troisième paramètre
d’ioctl(2) est ignoré. Seul un processus privilégié (i.e.
disposant du droit CAP_SYS_RESOURCE) peut régler une fréquence
supérieure à celle spécifiée dans
/proc/sys/dev/rtc/max-user-freq.
RTC_EPOCH_READ, RTC_EPOCH_SET
De nombreuses RTC codent l’année dans un registre de 8 bits,
interprété soit comme un nombre binaire de 8 bits, soit comme un
nombre BCD. Dans les deux cas, le nombre est interprété
relativement à l’Epoch de cette RTC. L’Epoch de la RTC est
initialisé à 1900 sur la plupart des systèmes, sauf sur Alpha et
Mips où il peut être initialisé à 1952, 1980 ou 2000, suivant la
valeur du registre RTC destiné à l’année. Avec certaines RTC,
ces opérations peuvent être utilisées respectivement pour lire
ou régler l’Epoch de la RTC. Le troisième paramètre ioctl(2) est
respectivement un unsigned long * ou un unsigned long, et la
valeur de retour (ou assignée) est l’Epoch. Pour régler l’Epoch
RTC, le processus doit être privilégié (i.e. disposer du droit
CAP_SYS_TIME).
RTC_WKALM_RD, RTC_WKALM_SET
Certaines RTC disposent d’une interface pour les alarmes plus
puissante, utilisant ces ioctl pour lire ou écrire l’heure de
l’alarme de la RTC avec cette structure :
struct rtc_wkalrm {
unsigned char enabled;
unsigned char pending;
struct rtc_time time;
};
L’attribut enabled est utilisé pour activer ou désactiver
l’interruption venant de l’alarme, ou pour lire son état
actuel ; lorsque ces appels sont utilisés, RTC_AIE_ON et
RTC_AIE_OFF ne sont pas utilisés. L’attribut pending est utilisé
par RTC_WKALM_RD pour signaler une interruption en attente
(c’est en général inutile sous Linux, excepté lors du dialogue
avec la RTC gérée par un microcode EFI). Le champ time est
autant utilisé par RTC_ALM_READ et RTC_ALM_SET, excepté que les
champs tm_mday, tm_mon et tm_year sont également valides. Un
pointeur vers cette structure doit être passé en troisième
paramètre ioctl(2).
FICHIERS
/dev/rtc, /dev/rtc0, /dev/rtc1 : fichiers spéciaux en mode caractère
des différentes RTC.
/proc/driver/rtc : état de la (première) RTC.
NOTES
Lorsque l’horloge du noyau est synchronisée avec une référence externe
en utilisant adjtimex(2), le noyau met à jour une RTC désignée toutes
les 11 minutes. Pour y parvenir, le noyau doit arrêter brièvement les
interruptions périodiques, ce qui peut affecter les programmes
utilisant cette RTC.
L’Epoch d’une RTC n’a rien à voir avec l’Epoch POSIX, utilisé
uniquement pour l’horloge système.
Si l’année relative à l’Epoch de la RTC et au registre de l’année est
inférieure à 1970, on considère que l’année est de 100 ans supérieure,
c.-à-d. entre 2000 et 2069.
Certaines RTC gèrent les caractères génériques (« wildcard ») dans les
champs des alarmes, destinés aux scénarios comme les alarmes
périodiques toutes les quinze minutes après chaque heure, ou au premier
jour de chaque mois. Une telle utilisation n’est pas portable ; un code
en espace utilisateur portable n’attend qu’une seule interruption
d’alarme, puis désactivera ou réinitialisera cette alarme après l’avoir
reçue.
Certaines RTC gèrent des interruptions de périodes multiples d’une
seconde plutôt qu’en fractions de secondes, des alarmes multiples, la
programmation de signaux de sortie d’horloge, la mémoire non volatile,
et d’autres possibilités matérielles qui ne sont pas accessibles par
cette API.
VOIR AUSSI
date(1), adjtimex(2), gettimeofday(2), settimeofday(2), stime(2),
time(2), gmtime(3), time(7), hwclock(8),
/usr/src/linux/Documentation/rtc.txt
COLOPHON
Cette page fait partie de la publication 3.23 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent être trouvées à l’adresse
http://www.kernel.org/doc/man-pages/.
TRADUCTION
Cette page de manuel a été traduite et mise à jour par Christophe
Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par
Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian sont
directement gérées par Simon Paillard
<simon.paillard@resel.enst-bretagne.fr> et l’équipe francophone de
traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document
en utilisant la commande « man -L C <section> <page_de_man> ».