From 6cf8b663e7d7cb1e827b6d9c90e694ea583f6f87 Mon Sep 17 00:00:00 2001 From: Stewart Smith Date: Fri, 6 Mar 2015 13:22:09 +1100 Subject: Refactor fsp-rtc.c to not call fsp_sync_msg (and thus pollers) with lock held We introduce simple state machine, have liberal assert()s and very clearly indicate what's protected by the lock (everything). We also stop waiting for the initial RTC response on boot, which will ever so slightly speed up booting. Signed-off-by: Stewart Smith --- doc/opal-api/opal-rtc-read-3.txt | 46 +++++++++++++++++++++++++++++++++++++++ doc/opal-api/opal-rtc-write-4.txt | 7 ++++++ 2 files changed, 53 insertions(+) create mode 100644 doc/opal-api/opal-rtc-read-3.txt create mode 100644 doc/opal-api/opal-rtc-write-4.txt (limited to 'doc') 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. -- cgit v1.1