[Skiboot] [PATCH 005/110] doc: Make OPAL_CONSOLE_* docs pretty

[Stewart Smith]

Signed-off-by: Stewart Smith <stewart at linux.ibm.com>
---
 doc/opal-api/opal-console-read-write-1-2.rst | 62 ++++++++++++--------
 1 file changed, 37 insertions(+), 25 deletions(-)

diff --git a/doc/opal-api/opal-console-read-write-1-2.rst b/doc/opal-api/opal-console-read-write-1-2.rst
index 6d6c0ff03b9c..60cd0a6dd06f 100644
--- a/doc/opal-api/opal-console-read-write-1-2.rst
+++ b/doc/opal-api/opal-console-read-write-1-2.rst
@@ -1,12 +1,20 @@
 OPAL Console calls
 ==================
 
-There are four OPAL calls relating to the OPAL console: ::
-
-  #define OPAL_CONSOLE_WRITE			1
-  #define OPAL_CONSOLE_READ			2
-  #define OPAL_CONSOLE_WRITE_BUFFER_SPACE		25
-  #define OPAL_CONSOLE_FLUSH			117
+There are four OPAL calls relating to the OPAL console:
+
++---------------------------------------------+--------------+------------------------+----------+-----------------+
+| Name                                        | API Token ID | Introduced             | Required | Notes           |
+|                                             |              |                        | as of    |                 |
++---------------------------------------------+--------------+------------------------+----------+-----------------+
+| :ref:`OPAL_CONSOLE_WRITE`                   |   1          | v1.0 (Initial Release) | POWER8   |                 |
++---------------------------------------------+--------------+------------------------+----------+-----------------+
+| :ref:`OPAL_CONSOLE_READ`                    |   2          | v1.0 (Initial Release) | POWER8   |                 |
++---------------------------------------------+--------------+------------------------+----------+-----------------+
+| :ref:`OPAL_CONSOLE_WRITE_BUFFER_SPACE`      |  25          | v1.0 (Initial Release) | POWER8   |                 |
++---------------------------------------------+--------------+------------------------+----------+-----------------+
+| :ref:`OPAL_CONSOLE_FLUSH`                   | 117          | :ref:`skiboot-5.1.13`  | POWER9   |                 |
++---------------------------------------------+--------------+------------------------+----------+-----------------+
 
 The OPAL console calls can support multiple consoles. Each console MUST
 be represented in the device tree.
@@ -16,6 +24,8 @@ for it to simply be an in-memory buffer and only support writing.
 
 [TODO: details on device tree specs for console]
 
+.. _OPAL_CONSOLE_WRITE:
+
 OPAL_CONSOLE_WRITE
 ------------------
 
@@ -25,12 +35,12 @@ Parameters: ::
   int64_t *length,
   const uint8_t *buffer
 
-Returns: ::
+Returns:
 
-  OPAL_SUCCESS
-  OPAL_PARAMETER - invalid term_number
-  OPAL_CLOSED - console device closed
-  OPAL_BUSY_EVENT - unable to write any of buffer
+ - :ref:`OPAL_SUCCESS`
+ - :ref:`OPAL_PARAMETER` on invalid term_number
+ - :ref:`OPAL_CLOSED` if console device closed
+ - :ref:`OPAL_BUSY_EVENT` if unable to write any of buffer
 
 ``term_number`` is the terminal number as represented in the device tree.
 ``length`` is a pointer to the length of buffer.
@@ -46,15 +56,17 @@ Parameters: ::
   int64_t term_number
   int64_t *length
 
-Returns: ::
+Returns:
 
-  OPAL_SUCCESS
-  OPAL_PARAMETER - invalid term_number
+ - :ref:`OPAL_SUCCESS`
+ - :ref:`OPAL_PARAMETER` on invalid term_number
 
 Returns the available buffer length for OPAL_CONSOLE_WRITE in ``length``.
 This call can be used to help work out if there is sufficient buffer
 space to write your full message to the console with OPAL_CONSOLE_WRITE.
 
+.. _OPAL_CONSOLE_READ:
+
 OPAL_CONSOLE_READ
 -----------------
 
@@ -64,13 +76,13 @@ Parameters: ::
   int64_t *length
   uint8_t *buffer
 
-Returns: ::
+Returns:
 
-  OPAL_SUCCESS
-  OPAL_PARAMETER - invalid term_number
-  OPAL_CLOSED
+ - :ref:`OPAL_SUCCESS`
+ - :ref:`OPAL_PARAMETER` on invalid term_number
+ - :ref:`OPAL_CLOSED`
 
-Use OPAL_POLL_EVENTS for how to determine
+Use :ref:`OPAL_POLL_EVENTS` for how to determine
 
 OPAL_CONSOLE_FLUSH
 ------------------
@@ -79,10 +91,10 @@ Parameters: ::
 
   int64_t term_number
 
-Returns: ::
+Returns:
 
-	OPAL_SUCCESS
-	OPAL_UNSUPPORTED - the console does not implement a flush call
-	OPAL_PARAMETER - invalid term_number
-	OPAL_PARTIAL - more to flush, call again
-	OPAL_BUSY - nothing was flushed this call
+ - :ref:`OPAL_SUCCESS`
+ - :ref:`OPAL_UNSUPPORTED` if the console does not implement a flush call
+ - :ref:`OPAL_PARAMETER` on invalid term_number
+ - :ref:`OPAL_PARTIAL` if more to flush, call again
+ - :ref:`OPAL_BUSY` if nothing was flushed this call
-- 
2.21.0