===============================
OPAL Real Time Clock (RTC) APIs
===============================

.. _OPAL_RTC_READ:

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, :ref:`OPAL_RTC_READ` is likely to first return
:ref:`OPAL_BUSY_EVENT`, requiring the caller to wait until the :ref:`OPAL_EVENT_RTC` event
has been signaled. Once the event has been signaled, a subsequent
:ref:`OPAL_RTC_READ` call will retrieve the time. Since the :ref:`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 :ref:`OPAL_RTC_WRITE` rather
than this read request.

The following code is one way to correctly issue and then wait for a response:

.. code-block:: c

    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 :ref:`OPAL_RTC_READ` backends are asynchronous, there is
no requirement for them to be - it is valid for :ref:`OPAL_RTC_READ` to immediately
return the retreived value rather than :ref:`OPAL_BUSY_EVENT`.

**TODO**: describe/document format of arguments.

Return codes
------------

:ref:`OPAL_SUCCESS`
  parameters now contain the current time, or one read from cache.

:ref:`OPAL_HARDWARE`
  error in retrieving the time. May be transient error,
  may be permanent.

:ref:`OPAL_PARAMETER`
  year_month_day or hour_minute_second_millisecond parameters are NULL

:ref:`OPAL_INTERNAL_ERROR`
  something went wrong, Possibly reported in error log.
  This can be a transient error

:ref:`OPAL_BUSY_EVENT`
  request is in flight

:ref:`OPAL_BUSY`
  request may be in flight

.. _OPAL_RTC_WRITE:

OPAL_RTC_WRITE
==============

:ref:`OPAL_RTC_WRITE` is much like :ref:`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.

Format of the time is the same as for :ref:`OPAL_RTC_READ`.