[Skiboot] [PATCH 04/11] interrupts: Rewrite/correct doc for opal_set/get_xive

[Benjamin Herrenschmidt]

Signed-off-by: Benjamin Herrenschmidt <benh at kernel.crashing.org>
---
 doc/opal-api/opal-get-xive-20.rst | 28 ++++++++++----------------
 doc/opal-api/opal-set-xive-19.rst | 42 ++++++++++++++++++++++++++-------------
 2 files changed, 38 insertions(+), 32 deletions(-)

diff --git a/doc/opal-api/opal-get-xive-20.rst b/doc/opal-api/opal-get-xive-20.rst
index 2d56a3a..65f4b0e 100644
--- a/doc/opal-api/opal-get-xive-20.rst
+++ b/doc/opal-api/opal-get-xive-20.rst
@@ -4,28 +4,20 @@ OPAL_GET_XIVE
 
    #define OPAL_GET_XIVE				20
 
-**WARNING:** following documentation is from old sources, and is possibly
-not representative of OPALv3 as implemented by skiboot. This should be
-used as a starting point for full documentation.
+The host calls this function to return the configuration of an
+interrupt source. See OPAL_SET_XIVE for details.
 
-The host calls this function to return the POWER XIVE server and priority
-values currently set in a PHB XIVE.
+Parameters
+----------
 
-``phb_id``
-  The ``phb_id`` parameter is the value from the PHB node ``ibm,opal-phbid``
-  property.
-
-``xive_number``
-  The ``xive_number`` is the index of an XIVE that corresponds to a particular
-  interrupt.
+``isn``
+  The ``isn`` is the global interrupt number being queried
 
 ``server_number``
-  the ``server_number`` returns the server (processor) that is set in this XIVE
+  the ``server_number`` returns the mangled server (processor)
+  that is set to receive that interrupt.
 
 ``priority``
-  the ``priority`` returns the interrupt priority value that is set in this XIVE
-
-
-This call returns the server and priority numbers from within the XIVE
-specified by the XIVE_number.
+  the ``priority`` returns the current interrupt priority setting
+  for that interrupt.
 
diff --git a/doc/opal-api/opal-set-xive-19.rst b/doc/opal-api/opal-set-xive-19.rst
index 871d9eb..f301e5e 100644
--- a/doc/opal-api/opal-set-xive-19.rst
+++ b/doc/opal-api/opal-set-xive-19.rst
@@ -4,28 +4,42 @@ OPAL_SET_XIVE
 
    #define OPAL_SET_XIVE				19
 
-**WARNING:** following documentation is from old sources, and is possibly
-not representative of OPALv3 as implemented by skiboot. This should be
-used as a starting point for full documentation.
+The host calls this function to set the server (target processor)
+and priority parameters of an interrupt source.
 
-The host calls this function to set the POWER XIVE server and priority
-parameters into the PHB XIVE.
+This can be also used to mask or unmask the interrupt (by changing
+the priority to 0xff one masks an interrupt).
+
+WARNINGS:
+
+ - For MSIs or generally edge sensitive interrupts, OPAL provides no
+   guarantee as to whether the interrupt will be latched if it occurs
+   while masked and replayed on unmask. It may or may not. The OS needs
+   to be aware of this. The current implementation will *not* replay,
+   neither on P8 nor on P9 XICS emulation.
+
+ - When masking, there is no guarantee that the interrupt will not
+   still occur after this call returns. The reason is that it might
+   already be on its way past the source controller and latched into one
+   of the presenters. There is however a guarantee that it won't replay
+   indefinitely so it's acceptable for the OS to simply ignore it.
 
 Parameters
 ----------
 
-``phb_id``
-  is the value from the PHB node ibm,opal-phbid property.
+``isn``
+  This is a global interrupt number as obtained from the device-tree
+  "interrupts" or "interrupt-map" properties.
 
-``xive_number``
-  is the index of an XIVE that corresponds to a particular
-  interrupt
-
-``service_number``
-  is the server (processor) that is to receive the
-  interrupt request
+``server_number``
+  is the mangled server (processor) that is to receive the
+  interrupt request. The mangling means that the actual processor
+  number is shifted left by 2 bits, the bottom bits representing
+  the "link". However links aren't supported in OPAL so the bottom
+  2 bits should be 0.
 
 ``priority``
   is the interrupt priority value applied to the interrupt
   (0=highest, 0xFF = lowest/disabled).
 
+
-- 
2.7.4