diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/opal-api/opal-rtc-read-3.txt | 46 | ||||
| -rw-r--r-- | doc/opal-api/opal-rtc-write-4.txt | 7 |
2 files changed, 53 insertions, 0 deletions
diff --git a/doc/opal-api/opal-rtc-read-3.txt b/doc/opal-api/opal-rtc-read-3.txt new file mode 100644 index 0000000..da6813a --- /dev/null +++ b/doc/opal-api/opal-rtc-read-3.txt @@ -0,0 +1,46 @@ +OPAL_RTC_READ +------------- + +Read the Real Time Clock. + +Parameters: + uint32_t* year_month_day + uint64_t* hour_minute_second_millisecond + +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 signalled, a subsequent +OPAL_RTC_READ call will retreive 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 signalled 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 diff --git a/doc/opal-api/opal-rtc-write-4.txt b/doc/opal-api/opal-rtc-write-4.txt new file mode 100644 index 0000000..d90c54a --- /dev/null +++ b/doc/opal-api/opal-rtc-write-4.txt @@ -0,0 +1,7 @@ +OPAL_RTC_WRITE +-------------- + +OPAL_RTC_WRITE is much like OPAL_RTC_READ in that it can be asynchronous. + +If multiple WRITES are issued before the first one completes, subsequent +writes are ignored. There can only be one write in flight at any one time. |