From patchwork Thu Nov 10 07:34:44 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Benjamin Herrenschmidt X-Patchwork-Id: 693089 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3tDw1S6W1wz9t1b for ; Thu, 10 Nov 2016 18:39:56 +1100 (AEDT) Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 3tDw1S5bPlzDvkB for ; Thu, 10 Nov 2016 18:39:56 +1100 (AEDT) X-Original-To: skiboot@lists.ozlabs.org Delivered-To: skiboot@lists.ozlabs.org Received: from gate.crashing.org (gate.crashing.org [63.228.1.57]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 3tDw0R4kR0zDvh5 for ; Thu, 10 Nov 2016 18:39:03 +1100 (AEDT) Received: from pasglop.au.ibm.com (localhost.localdomain [127.0.0.1]) by gate.crashing.org (8.14.1/8.13.8) with ESMTP id uAA7Ysa1030578; Thu, 10 Nov 2016 01:35:13 -0600 From: Benjamin Herrenschmidt To: skiboot@lists.ozlabs.org Date: Thu, 10 Nov 2016 18:34:44 +1100 Message-Id: <1478763292-23238-8-git-send-email-benh@kernel.crashing.org> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1478763292-23238-1-git-send-email-benh@kernel.crashing.org> References: <1478763292-23238-1-git-send-email-benh@kernel.crashing.org> Subject: [Skiboot] [PATCH 08/16] interrupts: Rewrite/correct doc for opal_set/get_xive X-BeenThere: skiboot@lists.ozlabs.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Mailing list for skiboot development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: skiboot-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Skiboot" Signed-off-by: Benjamin Herrenschmidt --- 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). +