rtc(4)

NUME
rtc - ceas în timp real

SINOPSIS
#include <linux/rtc.h>

int ioctl(fd, RTC_request, param);

DESCRIERE
Aceasta este interfața cu controlorii pentru ceasurile în timp real (RTC).

Majoritatea calculatoarelor au unul sau mai multe ceasuri hardware care înregistrează ora curentă a „orologiului (ceasul etalon)”. Acestea se numesc „ceasuri în timp real” („Real Time Clocks”: RTC). De obicei, unul dintre acestea are o baterie de rezervă, astfel încât înregistrează ora chiar și atunci când calculatorul este oprit. RTC-urile oferă adesea alarme și alte întreruperi.

Toate PC-urile i386 și sistemele bazate pe ACPI au un RTC compatibil cu cipul Motorola MC146818 de pe PC/AT original. În prezent, un astfel de RTC este de obicei integrat în chipset-ul plăcii de bază („south bridge”, puntea sudică) și utilizează o baterie de rezervă înlocuibilă de mărimea unei monede.

Sistemele non-PC, cum ar fi sistemele încorporate construite în jurul procesoarelor de tip „system-on-chip”, utilizează alte implementări. De obicei, acestea nu vor oferi aceeași funcționalitate ca și RTC-ul de pe un PC/AT.

  RTC vs ceas de sistem
RTC-urile nu trebuie confundate cu ceasul de sistem, care este un ceas software întreținut de nucleu și utilizat pentru a implementa gettimeofday(2) și time(2), precum și pentru a defini marcajele de timp pe fișiere și așa mai departe. Ceasul de sistem raportează secundele și microsecundele de la un punct de pornire, definit ca fiind POSIX Epoch: 1970-01-01 00:00:00 +0000 (UTC); (o implementare obișnuită numără întreruperile cronometrului, o dată pe „jiffy” (clipită), la o frecvență de 100, 250 sau 1000 Hz). Adică, se presupune că raportează ora „orologiului” (ceasului etalon), ceea ce fac și RTC-urile.

O diferență esențială între un RTC și ceasul de sistem este că RTC-urile funcționează chiar și atunci când sistemul se află într-o stare de consum redus de energie (inclusiv „oprit”), ceea ce nu este cazul ceasului de sistem. Până când nu este inițializat, ceasul de sistem poate raporta doar timpul de la pornirea sistemului, nu de la POSIX Epoch. Prin urmare, în momentul pornirii și după reluarea unei stări de consum redus de energie a sistemului, ceasul de sistem va fi adesea fixat la ora curentă a „orologiului” (ceasului etalon) cu ajutorul unui RTC. Sistemele fără un RTC trebuie să regleze ceasul sistemului folosind un alt ceas, poate prin rețea sau prin introducerea manuală a acestor date.

  Funcționalitatea RTC
RTC-urile pot fi citite și scrise cu hwclock(8), sau direct cu cererile ioctl(2) enumerate mai jos.

Pe lângă urmărirea datei și orei, multe RTC-uri pot genera și întreruperi.

•   la fiecare actualizare a ceasului (adică o dată pe secundă);

•   la intervale periodice cu o frecvență care poate fi stabilită la orice multiplu de putere de 2 din intervalul 2 Hz până la 8192 Hz;

•   la atingerea unei ore de alarmă specificate anterior.

Fiecare dintre aceste surse de întrerupere poate fi activată sau dezactivată separat. Pe multe sisteme, întreruperea de alarmă poate fi configurată ca un eveniment de trezire a sistemului, care poate relua sistemul dintr-o stare de putere redusă, cum ar fi suspendare la memoria RAM („Suspend-to-RAM”: STR, denumită S3 în sistemele ACPI), Hibernare („hibernation”, denumită S4 în sistemele ACPI) sau chiar „oprit” („off”, denumit S5 în sistemele ACPI). Pe unele sisteme, RTC-ul cu baterie nu poate emite întreruperi, dar un altul poate.

Dispozitivul /dev/rtc (sau /dev/rtc0, /dev/rtc1, etc.) poate fi deschis o singură dată (până când este închis) și este numai pentru citire. La read(2) și select(2), procesul apelant este blocat până când se primește următoarea întrerupere de la acel RTC. După întrerupere, procesul poate citi un număr întreg lung, din care cel mai puțin semnificativ octet conține o mască de biți care codifică tipurile de întreruperi care au avut loc, în timp ce ceilalți 3 octeți conțin numărul de întreruperi de la ultima citire read(2).

  interfața ioctl(2)
Următoarele cereri ioctl(2) sunt definite pe descriptorii de fișiere conectați la dispozitivele RTC:

RTC_RD_TIME
    Returnează ora acestui RTC în următoarea structură:

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

    Câmpurile din această structură au aceeași semnificație și aceleași intervale ca și în cazul structurii tm descrise la gmtime(3). Un indicator către această structură trebuie să fie transmis ca al treilea argument ioctl(2).

RTC_SET_TIME
    Stabilește ora acestui RTC la ora specificată de structura rtc_time la care indică al treilea argument ioctl(2). Pentru a stabili ora RTC-ului, procesul trebuie să fie privilegiat (adică să aibă capacitatea CAP_SYS_TIME).

RTC_ALM_READ
RTC_ALM_SET
    Citește și stabilește ora alarmei, pentru RTC-urile care acceptă alarme. Întreruperea alarmei trebuie să fie activată sau dezactivată separat cu ajutorul cererilor RTC_AIE_ON, RTC_AIE_OFF. Al treilea argument ioctl(2) este un indicator la o structură rtc_time. Se utilizează numai câmpurile tm_sec, tm_min și tm_hour ale acestei structuri.

RTC_IRQP_READ
RTC_IRQP_SET
    Citește și stabilește frecvența întreruperilor periodice, pentru RTC-urile care acceptă întreruperi periodice. Întreruperea periodică trebuie să fie activată sau dezactivată separat cu ajutorul cererilor RTC_PIE_ON, RTC_PIE_OFF. Al treilea argument ioctl(2) este un unsigned long * sau respectiv un unsigned long. Valoarea este frecvența în întreruperi pe secundă. Setul de frecvențe admisibile este reprezentat de multiplii de doi în intervalul 2-8192. Numai un proces privilegiat (adică unul care are capacitatea CAP_SYS_RESOURCE) poate stabili frecvențe peste valoarea specificată în /proc/sys/dev/rtc/max-user-freq; (acest fișier conține în mod implicit valoarea 64).

RTC_AIE_ON
RTC_AIE_OFF
    Activează sau dezactivează întreruperea alarmei, pentru RTC-urile care acceptă alarme. Al treilea argument ioctl(2) este ignorat.

RTC_UIE_ON
RTC_UIE_OFF
    Activează sau dezactivează întreruperea la fiecare actualizare a ceasului, pentru RTC-urile care acceptă această întrerupere o dată pe secundă. Al treilea argument ioctl(2) este ignorat.

RTC_PIE_ON
RTC_PIE_OFF
    Activează sau dezactivează întreruperea periodică, pentru RTC-urile care acceptă aceste întreruperi periodice. Al treilea argument ioctl(2) este ignorat. Numai un proces privilegiat (adică unul care are capacitatea CAP_SYS_RESOURCE) poate activa întreruperea periodică dacă frecvența este în prezent stabilită peste valoarea specificată în /proc/sys/dev/rtc/max-user-freq.

RTC_EPOCH_READ
RTC_EPOCH_SET
    Multe RTC-uri codifică anul într-un registru pe 8 biți care este interpretat fie ca un număr binar pe 8 biți, fie ca un număr BCD. În ambele cazuri, numărul este interpretat în raport cu Epoca acestui RTC. Epoca RTC este inițializată la 1900 pe majoritatea sistemelor, dar pe Alpha și MIPS poate fi inițializată și la 1952, 1980 sau 2000, în funcție de valoarea unui registru RTC pentru anul respectiv. În cazul unor RTC-uri, aceste operații pot fi utilizate pentru a citi sau, respectiv, pentru a stabili Epoca RTC-ului. Al treilea argument ioctl(2) este un unsigned long * sau un unsigned long, respectiv, valoarea returnată (sau atribuită) este Epoca. Pentru a stabili Epoca RTC-ului, procesul trebuie să fie privilegiat (adică să aibă capacitatea CAP_SYS_TIME).

RTC_WKALM_RD
RTC_WKALM_SET
    Unele RTC-uri acceptă o interfață de alarmă mai avansată, utilizând aceste ioctl-uri pentru a citi sau a scrie ora de alarmă a RTC-ului (respectiv) cu această structură:

        struct rtc_wkalrm {
            unsigned char enabled;
            unsigned char pending;
            struct rtc_time time;
        };

    Fanionul enabled este utilizat pentru a activa sau dezactiva întreruperea alarmei, sau pentru a citi starea curentă a acesteia; atunci când se utilizează aceste apeluri, RTC_AIE_ON și RTC_AIE_OFF nu sunt utilizate. Fanionul pending este utilizat de RTC_WKALM_RD pentru a raporta o întrerupere în așteptare (deci este în mare parte nefolositor pe Linux, cu excepția cazului în care se comunică cu RTC-ul gestionat de firmware-ul EFI). Câmpul time este la fel ca cel utilizat cu RTC_ALM_READ și RTC_ALM_SET, cu excepția faptului că sunt valabile și câmpurile tm_mday, tm_mon și tm_year. Un indicator la această structură trebuie transmis ca al treilea argument ioctl(2).

FIȘIERE

/dev/rtc
/dev/rtc0
/dev/rtc1
...
    Fișiere de dispozitive de caractere speciale RTC.

/proc/driver/rtc
    starea (primului) RTC.

NOTE
Atunci când ora sistemului nucleului este sincronizată cu o referință externă folosind adjtimex(2), acesta va actualiza periodic, la fiecare 11 minute, un RTC desemnat. Pentru a face acest lucru, nucleul trebuie să dezactiveze pentru scurt timp întreruperile periodice; acest lucru ar putea afecta programele care utilizează acel RTC.

Epoca unui RTC nu are nimic de-a face cu Epoca POSIX, care este utilizată doar pentru ceasul sistemului.

În cazul în care anul conform Epocii RTC și a registrului de ani este mai mic decât 1970, se presupune că este cu 100 de ani mai mare, adică între 2000 și 2069.

Unele RTC-uri acceptă valori „joker” în câmpurile de alarmă, pentru a permite scenarii cum ar fi alarme periodice la 15 minute după fiecare oră sau în prima zi a fiecărei luni. O astfel de utilizare nu este portabilă; codul portabil din spațiul utilizatorului se așteaptă la o singură întrerupere a alarmei și va dezactiva sau va reinițializa alarma după ce o primește.

Unele RTC-uri acceptă întreruperi periodice cu perioade care sunt mai degrabă multipli de secundă decât fracțiuni de secundă; alarme multiple; semnale de ceas de ieșire programabile; memorie nevolatilă; și alte capacități hardware care nu sunt expuse în prezent de această API.

CONSULTAȚI ȘI
date(1), adjtimex(2), gettimeofday(2), settimeofday(2), stime(2), time(2), gmtime(3), time(7), hwclock(8)

Documentation/rtc.txt în arborele sursă al nucleului Linux

TRADUCERE
Traducerea în limba română a acestui manual a fost făcută de Remus-Gabriel Chelu <remusgabriel.chelu@disroot.org>

Această traducere este documentație gratuită; citiți Licența publică generală GNU Versiunea 3 (https://www.gnu.org/licenses/gpl-3.0.html) sau o versiune ulterioară cu privire la condiții privind drepturile de autor. NU se asumă NICIO RESPONSABILITATE.

Dacă găsiți erori în traducerea acestui manual, vă rugăm să trimiteți un e-mail la translation-team-ro@lists.sourceforge.net.