RTC

Section : Manuel du programmeur Linux (4)
Mise à jour de la version anglaise : 26 novembre 2006
Index Menu principal

NOM

rtc - Horloge temps réel

SYNOPSIS

int ioctl(fd, RTC_request, param);

DESCRIPTION

Voici l'interface des pilotes pour les horloges temps réel (RTC) (Ndt : Real Time Clock).

La plupart des ordinateurs ont une ou plusieurs horloge(s) matérielle(s) qui enregistre(nt) l'heure courante. On les appelle « horloge(s) temps réel ». L'une d'entre elles possède normalement une pile comme alimentation de secours qui l'alimente de sorte qu'elle conserve le temps lorsque l'ordinateur est éteint. Les horloges temps réel fournissent souvent des alarmes et autres interruptions.

Tous les PC i386 et systèmes basés sur ACPI ont une horloge temps réel compatible avec le circuit Motorola MC146818 présent sur les premiers PC/AT. Aujourd'hui, une telle horloge est couramment implémentée dans le jeu de puce de la carte mère (south bridge) et utilise une pile de sauvegarde.

Sur les systèmes qui ne sont pas des PC, comme les systèmes embarqués construits autour de processeurs « système sur une puce », utilisent d'autres implémentations. Ils n'offrent généralement pas la même fonctionnalité que l'horloge temps réel d'un PC/AT.

RTC vs horloge système

L'horloge RTC ne doit pas être confondue avec l'horloge système qui est une horloge logicielle maintenue par le noyau et utilisée pour implémenter les appels système gettimeofday(2) et time(2), aussi bien que pour horodater les fichiers, etc. L'horloge système compte les secondes et microsecondes depuis le début de l'Époque POSIX, c'est-à-dire le 1er janvier 1970 à 00H00 UTC. (Une implémentation classique est de compter les interruptions de temporisation, une par « jiffy », à une fréquence de 100, 250 ou 1000 Hz.) Ainsi, cela est supposé indiquer l'heure, comme le fait également l'horloge RTC.

Une différence importante entre une horloge RTC et l'horloge système est que l'horloge RTC continue toujours à fonctionner lorsque l'alimentation du système est défaillante (y compris coupée), ce que ne peut pas faire l'horloge système.

Tant qu'elle n'est pas initialisée, l'horloge système ne peut qu'indiquer le temps écoulé depuis le démarrage du système, pas depuis l'Époque POSIX. Aussi, au démarrage ou après une récupération suite à une faiblesse de l'alimentation, l'horloge système est souvent mise à l'heure grâce à l'horloge RTC. Les systèmes qui ne possèdent pas d'horloge RTC doivent mettre à l'heure l'horloge système avec une autre horloge, peut-être au travers du réseau ou bien en entrant les données à la main.

Fonctionnalité RTC

Les horloges RTC peuvent être lues et configurées avec hwclock(8), ou directement avec les requêtes iotcl indiquées plus loin.

En plus de gérer la date et l'heure, la plupart des horloges RTC peut générer des interruptions

*: à chaque mise à jour de l'horloge (c'est-à-dire à chaque seconde) ;
*: à des intervalles périodiques dont la fréquence peut être configurée à tout multiple d'une puissance de deux dans l'intervalle 2 Hz à 8192 Hz ;
*: lorsqu'elle atteint une heure d'alarme précédemment spécifiée.

Chacune de ces interruptions peut être activée ou désactivée séparément. Sur beaucoup de systèmes, l'interruption d'alarme peut être configurée en tant qu'événement de réveil du système, qui peut reprendre le système à partir d'un état de faible consommation comme le mode de veille (Suspend-to-RAM : STR, appelé S3 sur les systèmes ACPI), mode d'hibernation (appelé S4 sur les systèmes ACPI) ou même « éteint » (appelé S5 sur les systèmes ACPI). Sur certains systèmes, l'horloge RTC sauvegardée par pile peut ne pas gérer les interruptions, auquel cas une autre peut le faire.

Le périphérique /dev/rtc (ou /dev/rtc0, /dev/rtc1, etc.) ne peut être ouvert qu'une seule fois (jusqu'à ce qu'il soit fermé) et en lecture seule. Dans le cas d'un read(2) ou d'un select(2), le processus appelant est bloqué jusqu'à ce que ne soit reçue la prochaine interruption de cette horloge RTC. À la suite de l'interruption, le processus peut lire un entier long. L'octet de poids faible de celui-ci contient un masque de bit codant les types d'interruption qui sont survenues alors que les trois autres octets contiennent le nombre d'interruptions depuis le dernier read(2).

Interface ioctl(2)

Les requêtes ioctl(2) sont définies pour les descripteurs de fichier connectés aux périphériques RTC :

RTC_RD_TIME

Renvoyer le temps 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;     /* inutilisé */
    int tm_yday;     /* inutilisé */
    int tm_isdst;    /* inutilisé */
};

Les champs de cette structure ont la même signification et les mêmes intervalles que la structure tm décrite dans gmtime(3). Un pointeur sur cette structure devrait être passé comme troisième argument de ioctl(2).

RTC_SET_TIME

Configurer le temps RTC avec la valeur temps spécifiée dans la structure rtc_time pointée par le troisième argument de ioctl(2). Pour pouvoir configurer l'horloge RTC, le processus doit être privilégié (c'est-à-dire avoir la capacité CAP_SYS_TIME).

RTC_ALM_READ, RTC_ALM_SET

Lire et configurer une alarme pour les horloges RTC qui prennent en charge les alarmes. L'interruption d'alarme doit être activée ou désactivée de manière séparée en utilisant les requêtes RTC_AIE_ON et RTC_AIE_OFF. Le troisième argument de ioctl(2) est un pointeur vers une structure rtc_time. tm_sec, tm_min et tm_hour de cette structure sont utilisés.

RTC_IRQP_READ, RTC_IRQP_SET

Lire et configurer la fréquence des interruptions périodiques pour les horloges RTC qui prennent en charge les interruptions périodiques. L'interruption périodique doit être activée ou désactivée de manière séparée en utilisant les requêtes RTC_PIE_ON et RTC_PIE_OFF. Le troisième argument de ioctl(2) est un unsigned long * ou un unsigned long, respectivement. La valeur est la fréquence des interruptions par seconde. L'ensemble des fréquences permises est les multiples de deux dans un intervalle de 2 à 8192. Seul un processus privilégié (c'est-à-dire qui a la capacité CAP_SYS_RESOURCE) peut configurer des fréquences supérieures à la valeur spécifiée dans /proc/sys/dev/rtc/max-user-freq. (Ce fichier contient la valeur 64 par défaut.)

RTC_AIE_ON, RTC_AIE_OFF

Activer ou désactiver l'interruption de l'alarme pour les horloges RTC qui prennent en charge les alarmes. Le troisième argument de ioctl(2) est ignoré.

RTC_UIE_ON, RTC_UIE_OFF

Activer ou désactiver l'interruption à chaque mise à jour de l'horloge, pour les horloges RTC qui prennent en charge l'interruption « une fois par seconde ». Le troisième argument de ioctl(2) est ignoré.

RTC_PIE_ON, RTC_PIE_OFF

Activer ou désactiver l'interruption périodique pour les horloges RTC qui prennent en charge ces interruptions périodiques. Le troisième argument de ioctl(2) est ignoré. Seul un processus privilégié (c'est-à-dire qui a la capacité CAP_SYS_RESOURCE) peut activer l'interruption périodique si la fréquence est actuellement supérieure à la valeur spécifiée dans /proc/sys/dev/rtc/max-user-freq.

RTC_EPOCH_READ, RTC_EPOCH_SET

Beaucoup d'horloges RTC encodent l'année dans un registre 8 bits qui est interprété soit comme un nombre binaire 8 bits, soit comme un nombre DCB. Dans les deux cas, le nombre est interprété relativement à l'Époque de cette horloge RTC. L'Époque de l'horloge RTC est initialisée à l'année 1900 sur la plupart des systèmes mais sur Alpha et Mips, elle peut être initialisée à 1952, 1980 ou 2000, suivant la valeur d'un registre RTC pour l'année. Avec certaines horloges RTC, ces opérations peuvent être utilisées pour lire ou configurer l'Époque de l'horloge RTC, respectivement. Le troisième argument de ioctl(2) est un unsigned long * ou un unsigned long, respectivement, et la valeur renvoyée (ou affectée) est l'Époque. Pour configurer l'Époque de l'horloge RTC, le processus doit être privilégié (c'est-à-dire avoir la capacité CAP_SYS_TIME).

RTC_WKALM_RD, RTC_WKALM_SET

Certaines horloges RTC prennent en charge une interface d'alarme plus puissante, en utilisant ces requêtes iotcl pour lire ou écrire la date de l'alarme de l'horloge RTC (respectivement) 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 d'alarme ou pour lire son état actuel ; lorsqu'on utilise ces appels, RTC_AIE_ON et RTC_AIE_OFF ne sont pas utilisés. L'attribut pending est utilisé par RTC_WKALM_RD pour indiquer une interruption pendante (dans la plupart des cas, inutile sous Linux, sauf lorsqu'on demande la gestion de l'horloge RTC par micrologiciel EFI). Le champ time est utilisé avec RTC_ALM_READ et RTC_ALM_SET à condition que les champs tm_mday, tm_mon, et tm_year soient également valides. Un pointeur sur cette structure doit être passé en tant que troisième argument à ioctl(2).

FICHIERS

/dev/rtc, /dev/rtc0, /dev/rtc1, etc : fichiers périphériques de caractère spécial RTC.

/proc/driver/rtc : état de la (première) horloge RTC.

NOTES

Lorsque l'horloge système du noyau est synchronisée avec une référence externe en utilisant adjtimex(2), il mettra à jour une horloge RTC désignée périodiquement toutes les 11 minutes. Pour ce faire, le noyau doit désactiver brièvement les interruptions périodiques ; cela peut affecter les programmes qui utilisent cette horloge RTC.

L'Époque de l'horloge RTC n'a rien à voir avec l'Époque POSIX qui est seulement utilisée pour l'horloge système.

Si l'année de l'Époque de l'horloge RTC et le registre année est moins que 1970, on suppose alors que l'on est 100 ans plus tard, c'est-à-dire entre 2000 et 2069.

Certaines horloges RTC prennent en charge des valeurs avec « jokers » dans les champs de l'alarme afin de prendre en charge des scenarii comme des alarmes périodes à la quinzième minute après chaque heure, ou le premier jour de chaque mois. Une telle utilisation n'est pas portable ; du code portable en espace utilisateur attend une seule interruption d'alarme et soit désactivera l'alarme, soit il la réinitalisera après avoir reçu l'interruption.

Certaines horloges RTC prennent en charge des interruptions périodiques dont les périodes sont des multiples de la seconde au lieu de fractions de seconde ; des alarmes multiples ; des signaux d'horloge de sortie programmables ; de la mémoire non volatile ; et d'autres possibilités matérielles qui ne sont actuellement pas décrites 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

TRADUCTION

Ce document est une traduction réalisée par Alain Portal <aportal AT univ-montp2 DOT fr> le 21 juillet 2006 et révisée le 17 juillet 2008.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 4 rtc ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.

Index

NOM

SYNOPSIS

DESCRIPTION

RTC vs horloge système
Fonctionnalité RTC
Interface ioctl(2)

Dernière mise à jour : 17 juillet 2008