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 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