blob: cb2387658fd5809de1ba659c321f7609d1932795 (
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
56
57
58
59
60
61
62
63
64
65
66
67
|
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
|
