blob: 13a0655b30d669f714108ca69841eb9de8fec354 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
|
OPAL_RTC_READ
-------------
Read the Real Time Clock.
Parameters:
uint32_t* year_month_day: the year, month and day formatted as follows:
- bits 0-15 is bcd formatted year (0100-9999)
- bits 16-23 is bcd formatted month (01-12)
- bits 24-31 is bcd formatted day (01-31)
uint64_t* hour_minute_second_millisecond: the hour, minute, second
and millisecond formatted as follows:
- bits 0-16 is reserved
- bits 17-24 is bcd formatted hour (00-23)
- bits 25-31 is bcd formatted minute (00-59)
- bits 32-39 is bcd formatted second (00-60)
- bits 40-63 is bcd formatted milliseconds (000000-999999)
Calling:
Since RTC calls can be pretty slow, OPAL_RTC_READ is likely to first return
OPAL_BUSY_EVENT, requiring the caller to wait until the OPAL_EVENT_RTC event
has been signaled. Once the event has been signaled, a subsequent
OPAL_RTC_READ call will retrieve the time. Since the OPAL_EVENT_RTC event is
used for both reading and writing the RTC, callers must be able to handle
the event being signaled for a concurrent in flight OPAL_RTC_WRITE rather
than this read request.
The following code is one way to correctly issue and then wait for a response:
int rc = OPAL_BUSY_EVENT;
while (rc == OPAL_BUSY_EVENT) {
rc = opal_rtc_read(&y_m_d, &h_m_s_ms);
if (rc == OPAL_BUSY_EVENT)
opal_poll_events(NULL);
}
Although as of writing all OPAL_RTC_READ backends are asynchronous, there is
no requirement for them to be - it is valid for OPAL_RTC_READ to immediately
return the retreived value rather than OPAL_BUSY_EVENT.
TODO: describe/document format of arguments.
Return codes:
OPAL_SUCCESS:
- parameters now contain the current time, or one read from cache.
OPAL_HARDWARE:
- error in retrieving the time. May be transient error,
may be permanent.
OPAL_PARAMETER:
- year_month_day or hour_minute_second_millisecond parameters are NULL
OPAL_INTERNAL_ERROR:
- something went wrong, Possibly reported in error log.
OPAL_BUSY_EVENT:
- request is in flight
|
