From a20d013cbc8f69b2661995698935306aae57a364 Mon Sep 17 00:00:00 2001 From: Benjamin Herrenschmidt Date: Mon, 14 Nov 2016 13:06:09 +1100 Subject: interrupts: Rewrite/correct doc for opal_set/get_xive Signed-off-by: Benjamin Herrenschmidt Signed-off-by: Stewart Smith --- 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(-) (limited to 'doc/opal-api') diff --git a/doc/opal-api/opal-get-xive-20.rst b/doc/opal-api/opal-get-xive-20.rst index 2d56a3af..65f4b0e5 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 871d9ebb..f301e5e5 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). + -- cgit v1.2.1