[Skiboot] [PATCH 027/110] doc: prettify OPAL_PCI_SET_PHB_CAPI_MODE

[Stewart Smith]

Signed-off-by: Stewart Smith <stewart at linux.ibm.com>
---
 .../opal-pci-set-phb-capi-mode-93.rst         | 60 ++++++++++++-------
 1 file changed, 37 insertions(+), 23 deletions(-)

diff --git a/doc/opal-api/opal-pci-set-phb-capi-mode-93.rst b/doc/opal-api/opal-pci-set-phb-capi-mode-93.rst
index 6a8d2be849d4..ffc4c6dc9fea 100644
--- a/doc/opal-api/opal-pci-set-phb-capi-mode-93.rst
+++ b/doc/opal-api/opal-pci-set-phb-capi-mode-93.rst
@@ -1,30 +1,47 @@
+.. _OPAL_PCI_SET_PHB_CAPI_MODE:
+
 OPAL_PCI_SET_PHB_CAPI_MODE
-===========================
+==========================
+
+.. code-block:: c
+
+   #define OPAL_PCI_SET_PHB_CAPI_MODE		93
+
+   /* CAPI modes for PHB */
+   enum {
+     OPAL_PHB_CAPI_MODE_PCIE		= 0,
+     OPAL_PHB_CAPI_MODE_CAPI		= 1,
+     OPAL_PHB_CAPI_MODE_SNOOP_OFF    = 2,
+     OPAL_PHB_CAPI_MODE_SNOOP_ON	= 3,
+     OPAL_PHB_CAPI_MODE_DMA		= 4,
+     OPAL_PHB_CAPI_MODE_DMA_TVT1	= 5,
+   };
 
-Switch the CAPP attached to the given PHB in one of the supported CAPI modes
+   int64_t opal_pci_set_phb_capi_mode(uint64_t phb_id, uint64_t mode, uint64_t pe_number);
+
+Switch the CAPP attached to the given PHB in one of the supported CAPI modes.
 
 Parameters
 ----------
+
 ``uint64_t phb_id``
   the ID of the PHB which identifies attached CAPP to perform mode switch on
-
 ``uint64_t mode``
   A mode id as described below
-
 ``pe_number``
   PE number for the initiating device
 
 Calling
 -------
 
-Switch CAPP attached to the given PHB in one of the following supported modes:
+Switch CAPP attached to the given PHB in one of the following supported modes: ::
 
-OPAL_PHB_CAPI_MODE_PCIE		= 0
-OPAL_PHB_CAPI_MODE_CAPI		= 1
-OPAL_PHB_CAPI_MODE_SNOOP_OFF    = 2
-OPAL_PHB_CAPI_MODE_SNOOP_ON	= 3
-OPAL_PHB_CAPI_MODE_DMA		= 4
-OPAL_PHB_CAPI_MODE_DMA_TVT1	= 5
+  OPAL_PHB_CAPI_MODE_PCIE		= 0
+  OPAL_PHB_CAPI_MODE_CAPI		= 1
+  OPAL_PHB_CAPI_MODE_SNOOP_OFF    = 2
+  OPAL_PHB_CAPI_MODE_SNOOP_ON	= 3
+  OPAL_PHB_CAPI_MODE_DMA		= 4
+  OPAL_PHB_CAPI_MODE_DMA_TVT1	= 5
 
 Modes `OPAL_PHB_CAPI_MODE_PCIE` and `OPAL_PHB_CAPI_MODE_CAPI` are used to
 enable/disable CAPP attached to the PHB.
@@ -42,8 +59,9 @@ requests maximum number of DMA read engines allocated to improve DMA read
 performance at cost of reduced bandwidth available to other traffic including
 CAPP-PSL transactions.
 
-Notes:
+Notes
 -----
+
 * If PHB is in PEC2 then requesting mode `OPAL_PHB_CAPI_MODE_DMA_TVT1` will
   allocate extra 16/8 dma read engines to the PHB depending on its stack
   (stack 0/ stack 1). This is needed to improve the Direct-GPU DMA read
@@ -55,20 +73,16 @@ Notes:
 
 Return Codes
 ------------
-OPAL_SUCCESS
-  Switch to the requested capi mode performed successfully.
 
-OPAL_PARAMETER
+:ref:`OPAL_SUCCESS`
+  Switch to the requested capi mode performed successfully.
+:ref:`OPAL_PARAMETER`
   The requested value of mode or phb_id parameter is not valid.
-
-OPAL_HARDWARE
+:ref:`OPAL_HARDWARE`
   An error occurred while switching the CAPP to requested mode.
-
-OPAL_UNSUPPORTED
+:ref:`OPAL_UNSUPPORTED`
   Switching to requested capi mode is not possible at the moment
-
-OPAL_RESOURCE
+:ref:`OPAL_RESOURCE`
   CAPP ucode not available hence activating CAPP not supported.
-
-OPAL_BUSY
+:ref:`OPAL_BUSY`
   CAPP is presently in recovery-mode and mode switch cannot be performed.
-- 
2.21.0