[Skiboot] [PATCH 049/110] doc: prettify and flesh out OPAL_FLASH_* call documentation

[Stewart Smith]

Signed-off-by: Stewart Smith <stewart at linux.ibm.com>
---
 doc/opal-api/opal-flash-110-111-112.rst | 65 ++++++++++++++-----------
 1 file changed, 37 insertions(+), 28 deletions(-)

diff --git a/doc/opal-api/opal-flash-110-111-112.rst b/doc/opal-api/opal-flash-110-111-112.rst
index e05bd2db504b..cee9bcc7dcea 100644
--- a/doc/opal-api/opal-flash-110-111-112.rst
+++ b/doc/opal-api/opal-flash-110-111-112.rst
@@ -1,7 +1,9 @@
 OPAL Flash calls
 ================
 
-There are three OPAL calls for interacting with flash devices: ::
+There are three OPAL calls for interacting with flash devices:
+
+.. code-block:: c
 
  #define OPAL_FLASH_READ	110
  #define OPAL_FLASH_WRITE	111
@@ -16,64 +18,71 @@ All operations on the flash device must be aligned to the block size of the
 flash. This applies to both offset and size arguments.
 
 This interface is asynchronous; all calls require a 'token' argument. On
-success, the calls will return ``OPAL_ASYNC_COMPLETION``, and an
+success, the calls will return :ref:`OPAL_ASYNC_COMPLETION`, and an
 opal_async_completion message will be sent (with the appropriate token
 argument) when the operation completes.
 
+.. note:: These calls can have higher than normal latency, spending many
+	  **milliseconds** inside OPAL. This is due to the OPAL_FLASH_* calls
+	  typically being backed by flash on the other side of the LPC bus,
+	  which has a maximum transfer rate of 5MB/sec, or to/from flash attached
+	  to the ast2400/ast2500 (the typical setup for OpenPOWER systems) of
+	  only 1.75MB/sec.
+
 All calls share the same return values:
 
-``OPAL_ASYNC_COMPLETION``
+:ref:`OPAL_ASYNC_COMPLETION`
   operation started, an async completion will be triggered with the ``token`` argument
-
-``OPAL_PARAMETER``
+:ref:`OPAL_PARAMETER`
   invalid flash id
-
-``OPAL_PARAMETER``
+:ref:`OPAL_PARAMETER`
   invalid size or offset (alignment, or access beyond end of device)
-
-``OPAL_BUSY``
+:ref:`OPAL_BUSY`
   flash in use
-
-``OPAL_HARDWARE``
+:ref:`OPAL_HARDWARE`
   error accessing flash device
 
+.. _OPAL_FLASH_READ:
+
 OPAL_FLASH_READ
 ---------------
 
-Parameters: ::
+.. code-block:: c
+
+    #define OPAL_FLASH_READ	110
 
-	uint64_t id
-	uint64_t offset
-	uint64_t buffer
-	uint64_t size
-	uint64_t token
+    int64_t opal_flash_read(uint64_t id, uint64_t offset, uint64_t buf,
+                            uint64_t size, uint64_t token);
 
 Reads from the specified flash id, at the specified offset, into the buffer.
 Will trigger an async completion with token when completed.
 
+.. _OPAL_FLASH_ERASE:
+
 OPAL_FLASH_ERASE
 ----------------
 
-Parameters: ::
+.. code-block:: c
 
-	uint64_t id
-	uint64_t offset
-	uint64_t size
-	uint64_t token
+   #define OPAL_FLASH_ERASE	112
+
+   int64_t opal_flash_erase(uint64_t id, uint64_t offset, uint64_t size,
+                            uint64_t token);
 
 Erases the specified flash id, at the specified offset and size.  Will trigger
 an async completion with token when completed.
 
+.. _OPAL_FLASH_WRITE:
+
 OPAL_FLASH_WRITE
 ----------------
 
-Parameters: ::
+.. code-block:: c
+
+   #define OPAL_FLASH_WRITE	111
 
-	uint64_t id
-	uint64_t offset
-	uint64_t buffer
-	uint64_t size
-	uint64_t token
+   int64_t opal_flash_write(uint64_t id, uint64_t offset, uint64_t buf,
+                            uint64_t size, uint64_t token);
 
 Writes buffer to the specified flash id, at the specified offset and size. The
 flash must be erased before being written. Will trigger an async completion with
-- 
2.21.0