doc: Make OPAL_RTC_READ docs pretty
+.. _OPAL_RTC_READ:
+
OPAL_RTC_READ
=============
@@ -24,15 +26,17 @@ Parameters
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
+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
-OPAL_RTC_READ call will retrieve the time. Since the OPAL_EVENT_RTC event is
+: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 OPAL_RTC_WRITE rather
+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: ::
+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) {
@@ -41,31 +45,31 @@ The following code is one way to correctly issue and then wait for a response: :
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.
+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
------------
-OPAL_SUCCESS
+:ref:`OPAL_SUCCESS`
parameters now contain the current time, or one read from cache.
-OPAL_HARDWARE
+:ref:`OPAL_HARDWARE`
error in retrieving the time. May be transient error,
may be permanent.
-OPAL_PARAMETER
+:ref:`OPAL_PARAMETER`
year_month_day or hour_minute_second_millisecond parameters are NULL
-OPAL_INTERNAL_ERROR
+:ref:`OPAL_INTERNAL_ERROR`
something went wrong, Possibly reported in error log.
This can be a transient error
-OPAL_BUSY_EVENT
+:ref:`OPAL_BUSY_EVENT`
request is in flight
-OPAL_BUSY
+:ref:`OPAL_BUSY`
request may be in flight
