From patchwork Wed Jul 27 07:43:18 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stewart Smith X-Patchwork-Id: 653186 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 3rznBl2vfXz9t23 for ; Wed, 27 Jul 2016 17:47:11 +1000 (AEST) Received: from ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 3rznBl1qSWzDrMY for ; Wed, 27 Jul 2016 17:47:11 +1000 (AEST) X-Original-To: skiboot@lists.ozlabs.org Delivered-To: skiboot@lists.ozlabs.org Received: from mx0a-001b2d01.pphosted.com (mx0b-001b2d01.pphosted.com [148.163.158.5]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 3rzn785jJ3zDrDt for ; Wed, 27 Jul 2016 17:44:04 +1000 (AEST) Received: from pps.filterd (m0098419.ppops.net [127.0.0.1]) by mx0b-001b2d01.pphosted.com (8.16.0.11/8.16.0.11) with SMTP id u6R7Y1dp115043 for ; Wed, 27 Jul 2016 03:44:02 -0400 Received: from e37.co.us.ibm.com (e37.co.us.ibm.com [32.97.110.158]) by mx0b-001b2d01.pphosted.com with ESMTP id 24edm9psh5-1 (version=TLSv1.2 cipher=AES256-SHA bits=256 verify=NOT) for ; Wed, 27 Jul 2016 03:44:00 -0400 Received: from localhost by e37.co.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Wed, 27 Jul 2016 01:43:59 -0600 Received: from d03dlp03.boulder.ibm.com (9.17.202.179) by e37.co.us.ibm.com (192.168.1.137) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Wed, 27 Jul 2016 01:43:56 -0600 X-IBM-Helo: d03dlp03.boulder.ibm.com X-IBM-MailFrom: stewart@linux.vnet.ibm.com Received: from b03cxnp07029.gho.boulder.ibm.com (b03cxnp07029.gho.boulder.ibm.com [9.17.130.16]) by d03dlp03.boulder.ibm.com (Postfix) with ESMTP id D5DEC19D8026 for ; Wed, 27 Jul 2016 01:43:30 -0600 (MDT) Received: from b03ledav003.gho.boulder.ibm.com (b03ledav003.gho.boulder.ibm.com [9.17.130.234]) by b03cxnp07029.gho.boulder.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id u6R7htrw11534634 for ; Wed, 27 Jul 2016 00:43:55 -0700 Received: from localhost (unknown [127.0.0.1]) by IMSVA (Postfix) with SMTP id C06AB6A041 for ; Wed, 27 Jul 2016 01:43:55 -0600 (MDT) X-IMSS-HAND-OFF-DIRECTIVE: 127.0.0.1:10026 Received: from birb.localdomain (unknown [9.81.197.209]) by b03ledav003.gho.boulder.ibm.com (Postfix) with SMTP id B66456A042; Wed, 27 Jul 2016 01:43:39 -0600 (MDT) Received: by birb.localdomain (Postfix, from userid 1000) id 8B6572721ECE; Wed, 27 Jul 2016 17:43:28 +1000 (AEST) From: Stewart Smith To: skiboot@lists.ozlabs.org Date: Wed, 27 Jul 2016 17:43:18 +1000 X-Mailer: git-send-email 2.7.4 In-Reply-To: <1469605404-13156-1-git-send-email-stewart@linux.vnet.ibm.com> References: <1469605404-13156-1-git-send-email-stewart@linux.vnet.ibm.com> X-TM-AS-GCONF: 00 X-Content-Scanned: Fidelis XPS MAILER x-cbid: 16072707-0024-0000-0000-00001432F90B X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 16072707-0025-0000-0000-0000430E189F Message-Id: <1469605404-13156-18-git-send-email-stewart@linux.vnet.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:, , definitions=2016-07-27_05:, , signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 spamscore=0 suspectscore=1 malwarescore=0 phishscore=0 adultscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1604210000 definitions=main-1607270080 Subject: [Skiboot] [RFC PATCH 17/23] doc/opal-api: rename .txt to .rst X-BeenThere: skiboot@lists.ozlabs.org X-Mailman-Version: 2.1.22 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: Stewart Smith --- doc/opal-api/opal-cec-power-down-5.rst | 25 +++ doc/opal-api/opal-cec-power-down-5.txt | 25 --- doc/opal-api/opal-cec-reboot-6-116.rst | 54 ++++++ doc/opal-api/opal-cec-reboot-6-116.txt | 54 ------ doc/opal-api/opal-check-token-80.rst | 23 +++ doc/opal-api/opal-check-token-80.txt | 23 --- doc/opal-api/opal-code-update-76-77-78.rst | 78 ++++++++ doc/opal-api/opal-code-update-76-77-78.txt | 78 -------- doc/opal-api/opal-console-read-write-1-2.rst | 80 ++++++++ doc/opal-api/opal-console-read-write-1-2.txt | 80 -------- doc/opal-api/opal-flash-110-111-112.rst | 72 +++++++ doc/opal-api/opal-flash-110-111-112.txt | 72 ------- doc/opal-api/opal-get-device-tree-118.rst | 24 +++ doc/opal-api/opal-get-device-tree-118.txt | 24 --- doc/opal-api/opal-get-msg-85.rst | 43 +++++ doc/opal-api/opal-get-msg-85.txt | 43 ----- doc/opal-api/opal-get-msi-39-40.rst | 46 +++++ doc/opal-api/opal-get-msi-39-40.txt | 46 ----- doc/opal-api/opal-get-xive-20.rst | 25 +++ doc/opal-api/opal-get-xive-20.txt | 25 --- doc/opal-api/opal-handle-interrupt.rst | 26 +++ doc/opal-api/opal-handle-interrupt.txt | 26 --- doc/opal-api/opal-int-eoi-124.rst | 20 ++ doc/opal-api/opal-int-eoi-124.txt | 20 -- doc/opal-api/opal-int-get-xirr-122.rst | 15 ++ doc/opal-api/opal-int-get-xirr-122.txt | 15 -- doc/opal-api/opal-int-set-cppr-123.rst | 16 ++ doc/opal-api/opal-int-set-cppr-123.txt | 16 -- doc/opal-api/opal-int-set-mfrr-125.rst | 15 ++ doc/opal-api/opal-int-set-mfrr-125.txt | 15 -- doc/opal-api/opal-invalid-call--1.rst | 6 + doc/opal-api/opal-invalid-call--1.txt | 6 - doc/opal-api/opal-led-get-set-114-115.rst | 55 ++++++ doc/opal-api/opal-led-get-set-114-115.txt | 55 ------ doc/opal-api/opal-messages.rst | 213 +++++++++++++++++++++ doc/opal-api/opal-messages.txt | 213 --------------------- doc/opal-api/opal-pci-get-phb-diag-data2-64.rst | 24 +++ doc/opal-api/opal-pci-get-phb-diag-data2-64.txt | 24 --- doc/opal-api/opal-pci-get-power-state-120.rst | 19 ++ doc/opal-api/opal-pci-get-power-state-120.txt | 19 -- doc/opal-api/opal-pci-get-presence-state-119.rst | 22 +++ doc/opal-api/opal-pci-get-presence-state-119.txt | 22 --- .../opal-pci-get-set-xive-reissue-35-36.rst | 17 ++ .../opal-pci-get-set-xive-reissue-35-36.txt | 17 -- doc/opal-api/opal-pci-map-pe-dma-window-44.rst | 92 +++++++++ doc/opal-api/opal-pci-map-pe-dma-window-44.txt | 92 --------- .../opal-pci-map-pe-dma-window-real-45.rst | 39 ++++ .../opal-pci-map-pe-dma-window-real-45.txt | 39 ---- doc/opal-api/opal-pci-map-pe-mmio-window-29.rst | 39 ++++ doc/opal-api/opal-pci-map-pe-mmio-window-29.txt | 39 ---- doc/opal-api/opal-pci-phb-mmio-enable-27.rst | 44 +++++ doc/opal-api/opal-pci-phb-mmio-enable-27.txt | 44 ----- doc/opal-api/opal-pci-set-mve-33.rst | 36 ++++ doc/opal-api/opal-pci-set-mve-33.txt | 36 ---- doc/opal-api/opal-pci-set-mve-enable-34.rst | 35 ++++ doc/opal-api/opal-pci-set-mve-enable-34.txt | 35 ---- doc/opal-api/opal-pci-set-pe-31.rst | 74 +++++++ doc/opal-api/opal-pci-set-pe-31.txt | 74 ------- doc/opal-api/opal-pci-set-peltv-32.rst | 52 +++++ doc/opal-api/opal-pci-set-peltv-32.txt | 52 ----- doc/opal-api/opal-pci-set-phb-mem-window-28.rst | 71 +++++++ doc/opal-api/opal-pci-set-phb-mem-window-28.txt | 71 ------- doc/opal-api/opal-pci-set-power-state-121.rst | 36 ++++ doc/opal-api/opal-pci-set-power-state-121.txt | 36 ---- doc/opal-api/opal-pci-set-xive-pe-37.rst | 30 +++ doc/opal-api/opal-pci-set-xive-pe-37.txt | 30 --- doc/opal-api/opal-pci-tce-kill-126.rst | 55 ++++++ doc/opal-api/opal-pci-tce-kill-126.txt | 55 ------ doc/opal-api/opal-poll-events.rst | 84 ++++++++ doc/opal-api/opal-poll-events.txt | 84 -------- doc/opal-api/opal-prd-msg-113.rst | 11 ++ doc/opal-api/opal-prd-msg-113.txt | 11 -- doc/opal-api/opal-read-write-tpo-103-104.rst | 15 ++ doc/opal-api/opal-read-write-tpo-103-104.txt | 15 -- doc/opal-api/opal-register-dump-region-101.rst | 43 +++++ doc/opal-api/opal-register-dump-region-101.txt | 43 ----- doc/opal-api/opal-reinit-cpus-70.rst | 29 +++ doc/opal-api/opal-reinit-cpus-70.txt | 29 --- doc/opal-api/opal-return-cpu-69.rst | 17 ++ doc/opal-api/opal-return-cpu-69.txt | 17 -- doc/opal-api/opal-rtc-read-3.rst | 55 ++++++ doc/opal-api/opal-rtc-read-3.txt | 55 ------ doc/opal-api/opal-rtc-write-4.rst | 9 + doc/opal-api/opal-rtc-write-4.txt | 9 - doc/opal-api/opal-sensor-read-88.rst | 33 ++++ doc/opal-api/opal-sensor-read-88.txt | 33 ---- doc/opal-api/opal-set-xive-19.rst | 24 +++ doc/opal-api/opal-set-xive-19.txt | 24 --- doc/opal-api/opal-sync-host-reboot-87.rst | 15 ++ doc/opal-api/opal-sync-host-reboot-87.txt | 15 -- doc/opal-api/opal-test-0.rst | 30 +++ doc/opal-api/opal-test-0.txt | 30 --- doc/opal-api/opal-unregister-dump-region-102.rst | 18 ++ doc/opal-api/opal-unregister-dump-region-102.txt | 18 -- doc/opal-api/opal-xscom-read-write-65-66.rst | 17 ++ doc/opal-api/opal-xscom-read-write-65-66.txt | 17 -- 96 files changed, 1921 insertions(+), 1921 deletions(-) create mode 100644 doc/opal-api/opal-cec-power-down-5.rst delete mode 100644 doc/opal-api/opal-cec-power-down-5.txt create mode 100644 doc/opal-api/opal-cec-reboot-6-116.rst delete mode 100644 doc/opal-api/opal-cec-reboot-6-116.txt create mode 100644 doc/opal-api/opal-check-token-80.rst delete mode 100644 doc/opal-api/opal-check-token-80.txt create mode 100644 doc/opal-api/opal-code-update-76-77-78.rst delete mode 100644 doc/opal-api/opal-code-update-76-77-78.txt create mode 100644 doc/opal-api/opal-console-read-write-1-2.rst delete mode 100644 doc/opal-api/opal-console-read-write-1-2.txt create mode 100644 doc/opal-api/opal-flash-110-111-112.rst delete mode 100644 doc/opal-api/opal-flash-110-111-112.txt create mode 100644 doc/opal-api/opal-get-device-tree-118.rst delete mode 100644 doc/opal-api/opal-get-device-tree-118.txt create mode 100644 doc/opal-api/opal-get-msg-85.rst delete mode 100644 doc/opal-api/opal-get-msg-85.txt create mode 100644 doc/opal-api/opal-get-msi-39-40.rst delete mode 100644 doc/opal-api/opal-get-msi-39-40.txt create mode 100644 doc/opal-api/opal-get-xive-20.rst delete mode 100644 doc/opal-api/opal-get-xive-20.txt create mode 100644 doc/opal-api/opal-handle-interrupt.rst delete mode 100644 doc/opal-api/opal-handle-interrupt.txt create mode 100644 doc/opal-api/opal-int-eoi-124.rst delete mode 100644 doc/opal-api/opal-int-eoi-124.txt create mode 100644 doc/opal-api/opal-int-get-xirr-122.rst delete mode 100644 doc/opal-api/opal-int-get-xirr-122.txt create mode 100644 doc/opal-api/opal-int-set-cppr-123.rst delete mode 100644 doc/opal-api/opal-int-set-cppr-123.txt create mode 100644 doc/opal-api/opal-int-set-mfrr-125.rst delete mode 100644 doc/opal-api/opal-int-set-mfrr-125.txt create mode 100644 doc/opal-api/opal-invalid-call--1.rst delete mode 100644 doc/opal-api/opal-invalid-call--1.txt create mode 100644 doc/opal-api/opal-led-get-set-114-115.rst delete mode 100644 doc/opal-api/opal-led-get-set-114-115.txt create mode 100644 doc/opal-api/opal-messages.rst delete mode 100644 doc/opal-api/opal-messages.txt create mode 100644 doc/opal-api/opal-pci-get-phb-diag-data2-64.rst delete mode 100644 doc/opal-api/opal-pci-get-phb-diag-data2-64.txt create mode 100644 doc/opal-api/opal-pci-get-power-state-120.rst delete mode 100644 doc/opal-api/opal-pci-get-power-state-120.txt create mode 100644 doc/opal-api/opal-pci-get-presence-state-119.rst delete mode 100644 doc/opal-api/opal-pci-get-presence-state-119.txt create mode 100644 doc/opal-api/opal-pci-get-set-xive-reissue-35-36.rst delete mode 100644 doc/opal-api/opal-pci-get-set-xive-reissue-35-36.txt create mode 100644 doc/opal-api/opal-pci-map-pe-dma-window-44.rst delete mode 100644 doc/opal-api/opal-pci-map-pe-dma-window-44.txt create mode 100644 doc/opal-api/opal-pci-map-pe-dma-window-real-45.rst delete mode 100644 doc/opal-api/opal-pci-map-pe-dma-window-real-45.txt create mode 100644 doc/opal-api/opal-pci-map-pe-mmio-window-29.rst delete mode 100644 doc/opal-api/opal-pci-map-pe-mmio-window-29.txt create mode 100644 doc/opal-api/opal-pci-phb-mmio-enable-27.rst delete mode 100644 doc/opal-api/opal-pci-phb-mmio-enable-27.txt create mode 100644 doc/opal-api/opal-pci-set-mve-33.rst delete mode 100644 doc/opal-api/opal-pci-set-mve-33.txt create mode 100644 doc/opal-api/opal-pci-set-mve-enable-34.rst delete mode 100644 doc/opal-api/opal-pci-set-mve-enable-34.txt create mode 100644 doc/opal-api/opal-pci-set-pe-31.rst delete mode 100644 doc/opal-api/opal-pci-set-pe-31.txt create mode 100644 doc/opal-api/opal-pci-set-peltv-32.rst delete mode 100644 doc/opal-api/opal-pci-set-peltv-32.txt create mode 100644 doc/opal-api/opal-pci-set-phb-mem-window-28.rst delete mode 100644 doc/opal-api/opal-pci-set-phb-mem-window-28.txt create mode 100644 doc/opal-api/opal-pci-set-power-state-121.rst delete mode 100644 doc/opal-api/opal-pci-set-power-state-121.txt create mode 100644 doc/opal-api/opal-pci-set-xive-pe-37.rst delete mode 100644 doc/opal-api/opal-pci-set-xive-pe-37.txt create mode 100644 doc/opal-api/opal-pci-tce-kill-126.rst delete mode 100644 doc/opal-api/opal-pci-tce-kill-126.txt create mode 100644 doc/opal-api/opal-poll-events.rst delete mode 100644 doc/opal-api/opal-poll-events.txt create mode 100644 doc/opal-api/opal-prd-msg-113.rst delete mode 100644 doc/opal-api/opal-prd-msg-113.txt create mode 100644 doc/opal-api/opal-read-write-tpo-103-104.rst delete mode 100644 doc/opal-api/opal-read-write-tpo-103-104.txt create mode 100644 doc/opal-api/opal-register-dump-region-101.rst delete mode 100644 doc/opal-api/opal-register-dump-region-101.txt create mode 100644 doc/opal-api/opal-reinit-cpus-70.rst delete mode 100644 doc/opal-api/opal-reinit-cpus-70.txt create mode 100644 doc/opal-api/opal-return-cpu-69.rst delete mode 100644 doc/opal-api/opal-return-cpu-69.txt create mode 100644 doc/opal-api/opal-rtc-read-3.rst delete mode 100644 doc/opal-api/opal-rtc-read-3.txt create mode 100644 doc/opal-api/opal-rtc-write-4.rst delete mode 100644 doc/opal-api/opal-rtc-write-4.txt create mode 100644 doc/opal-api/opal-sensor-read-88.rst delete mode 100644 doc/opal-api/opal-sensor-read-88.txt create mode 100644 doc/opal-api/opal-set-xive-19.rst delete mode 100644 doc/opal-api/opal-set-xive-19.txt create mode 100644 doc/opal-api/opal-sync-host-reboot-87.rst delete mode 100644 doc/opal-api/opal-sync-host-reboot-87.txt create mode 100644 doc/opal-api/opal-test-0.rst delete mode 100644 doc/opal-api/opal-test-0.txt create mode 100644 doc/opal-api/opal-unregister-dump-region-102.rst delete mode 100644 doc/opal-api/opal-unregister-dump-region-102.txt create mode 100644 doc/opal-api/opal-xscom-read-write-65-66.rst delete mode 100644 doc/opal-api/opal-xscom-read-write-65-66.txt diff --git a/doc/opal-api/opal-cec-power-down-5.rst b/doc/opal-api/opal-cec-power-down-5.rst new file mode 100644 index 0000000..d18912a --- /dev/null +++ b/doc/opal-api/opal-cec-power-down-5.rst @@ -0,0 +1,25 @@ +OPAL_CEC_POWER_DOWN +------------------- + +#define OPAL_CEC_POWER_DOWN 5 + +int64 opal_cec_power_down(uint64 request) + +Arguments: + + uint64 request values as follows: + 0 - Power down normally + 1 - Power down immediately + +This OPAL call requests OPAL to power down the system. The exact difference +between a normal and immediate shutdown is platform specific. + +Current Linux kernels just use power down normally (0). It is valid for a +platform to only support some types of power down operations. + +Return Values: +OPAL_SUCCESS: the power down was updated successful +OPAL_BUSY: unable to power down, try again later +OPAL_PARAMETER: a parameter was incorrect +OPAL_INTERNAL_ERROR: hal code sent incorrect data to hardware device +OPAL_UNSUPPORTED: this platform does not support being powered off. diff --git a/doc/opal-api/opal-cec-power-down-5.txt b/doc/opal-api/opal-cec-power-down-5.txt deleted file mode 100644 index d18912a..0000000 --- a/doc/opal-api/opal-cec-power-down-5.txt +++ /dev/null @@ -1,25 +0,0 @@ -OPAL_CEC_POWER_DOWN -------------------- - -#define OPAL_CEC_POWER_DOWN 5 - -int64 opal_cec_power_down(uint64 request) - -Arguments: - - uint64 request values as follows: - 0 - Power down normally - 1 - Power down immediately - -This OPAL call requests OPAL to power down the system. The exact difference -between a normal and immediate shutdown is platform specific. - -Current Linux kernels just use power down normally (0). It is valid for a -platform to only support some types of power down operations. - -Return Values: -OPAL_SUCCESS: the power down was updated successful -OPAL_BUSY: unable to power down, try again later -OPAL_PARAMETER: a parameter was incorrect -OPAL_INTERNAL_ERROR: hal code sent incorrect data to hardware device -OPAL_UNSUPPORTED: this platform does not support being powered off. diff --git a/doc/opal-api/opal-cec-reboot-6-116.rst b/doc/opal-api/opal-cec-reboot-6-116.rst new file mode 100644 index 0000000..4d2b2ca --- /dev/null +++ b/doc/opal-api/opal-cec-reboot-6-116.rst @@ -0,0 +1,54 @@ +OPAL_CEC_REBOOT and OPAL_CEC_REBOOT2 +------------------------------------ + +#define OPAL_CEC_REBOOT 6 +#define OPAL_CEC_REBOOT2 116 + +There are two opal calls to invoke system reboot. +OPAL_CEC_REBOOT: Used for normal reboot by Linux host. + +OPAL_CEC_REBOOT2: Newly introduced to handle abnormal system reboots. +The Linux kernel will make this OPAL call when it has to terminate +abruptly due to an anomalous condition. The kernel will push some system +state context to OPAL, which will in turn push it down to the BMC for +further analysis. + +OPAL_CEC_REBOOT +--------------- +Syntax: +int64_t opal_cec_reboot(void) + +Input parameters: +None. + +System reboots normally. + +OPAL_CEC_REBOOT2 +---------------- +Syntax: +int64_t opal_cec_reboot2(uint32_t reboot_type, char *diag) + +Input parameters: + @reboot_type Type of reboot. (see below) + @diag Null-terminated string. + +Depending on reboot type, this call will carry out additional steps +before triggering reboot. + +Supported reboot types: +---------------------- +OPAL_REBOOT_NORMAL = 0 + Behavior is as similar to that of opal_cec_reboot() + +OPAL_REBOOT_PLATFORM_ERROR = 1 + Log an error to the BMC and then trigger a system checkstop, using + the information provided by 'ibm,sw-checkstop-fir' property in the + device-tree. Post the checkstop trigger, OCC/BMC will collect + relevant data for error analysis and trigger a reboot. + + In absence of 'ibm,sw-checkstop-fir' device property, this function + will return with OPAL_UNSUPPORTED and no reboot will be triggered. + +Unsupported Reboot type + For unsupported reboot type, this function will return with + OPAL_UNSUPPORTED and no reboot will be triggered. diff --git a/doc/opal-api/opal-cec-reboot-6-116.txt b/doc/opal-api/opal-cec-reboot-6-116.txt deleted file mode 100644 index 4d2b2ca..0000000 --- a/doc/opal-api/opal-cec-reboot-6-116.txt +++ /dev/null @@ -1,54 +0,0 @@ -OPAL_CEC_REBOOT and OPAL_CEC_REBOOT2 ------------------------------------- - -#define OPAL_CEC_REBOOT 6 -#define OPAL_CEC_REBOOT2 116 - -There are two opal calls to invoke system reboot. -OPAL_CEC_REBOOT: Used for normal reboot by Linux host. - -OPAL_CEC_REBOOT2: Newly introduced to handle abnormal system reboots. -The Linux kernel will make this OPAL call when it has to terminate -abruptly due to an anomalous condition. The kernel will push some system -state context to OPAL, which will in turn push it down to the BMC for -further analysis. - -OPAL_CEC_REBOOT ---------------- -Syntax: -int64_t opal_cec_reboot(void) - -Input parameters: -None. - -System reboots normally. - -OPAL_CEC_REBOOT2 ----------------- -Syntax: -int64_t opal_cec_reboot2(uint32_t reboot_type, char *diag) - -Input parameters: - @reboot_type Type of reboot. (see below) - @diag Null-terminated string. - -Depending on reboot type, this call will carry out additional steps -before triggering reboot. - -Supported reboot types: ----------------------- -OPAL_REBOOT_NORMAL = 0 - Behavior is as similar to that of opal_cec_reboot() - -OPAL_REBOOT_PLATFORM_ERROR = 1 - Log an error to the BMC and then trigger a system checkstop, using - the information provided by 'ibm,sw-checkstop-fir' property in the - device-tree. Post the checkstop trigger, OCC/BMC will collect - relevant data for error analysis and trigger a reboot. - - In absence of 'ibm,sw-checkstop-fir' device property, this function - will return with OPAL_UNSUPPORTED and no reboot will be triggered. - -Unsupported Reboot type - For unsupported reboot type, this function will return with - OPAL_UNSUPPORTED and no reboot will be triggered. diff --git a/doc/opal-api/opal-check-token-80.rst b/doc/opal-api/opal-check-token-80.rst new file mode 100644 index 0000000..4c5f7c3 --- /dev/null +++ b/doc/opal-api/opal-check-token-80.rst @@ -0,0 +1,23 @@ +OPAL_CHECK_TOKEN +---------------- + +This OPAL call allows the host OS to determine if a particular OPAL call is present +on a system. This allows for simple compatibility between OPAL versions and different +OPAL implementations/platforms. + +One parameter is accepted: the OPAL token number. + +OPAL_CHECK_TOKEN will return: + +enum OpalCheckTokenStatus { + OPAL_TOKEN_ABSENT = 0, + OPAL_TOKEN_PRESENT = 1 +}; + +indicating the presence/absence of the particular OPAL_CALL. + +OPAL_CHECK_TOKEN is REQUIRED to be implemented by a conformant OPAL implementation. + +For skiboot, only positively ancient internal-to-IBM versions were missing +OPAL_CHECK_TOKEN. In this case, OPAL_PARAMETER would be returned. There is no +reason for a host OS to support this behaviour. diff --git a/doc/opal-api/opal-check-token-80.txt b/doc/opal-api/opal-check-token-80.txt deleted file mode 100644 index 4c5f7c3..0000000 --- a/doc/opal-api/opal-check-token-80.txt +++ /dev/null @@ -1,23 +0,0 @@ -OPAL_CHECK_TOKEN ----------------- - -This OPAL call allows the host OS to determine if a particular OPAL call is present -on a system. This allows for simple compatibility between OPAL versions and different -OPAL implementations/platforms. - -One parameter is accepted: the OPAL token number. - -OPAL_CHECK_TOKEN will return: - -enum OpalCheckTokenStatus { - OPAL_TOKEN_ABSENT = 0, - OPAL_TOKEN_PRESENT = 1 -}; - -indicating the presence/absence of the particular OPAL_CALL. - -OPAL_CHECK_TOKEN is REQUIRED to be implemented by a conformant OPAL implementation. - -For skiboot, only positively ancient internal-to-IBM versions were missing -OPAL_CHECK_TOKEN. In this case, OPAL_PARAMETER would be returned. There is no -reason for a host OS to support this behaviour. diff --git a/doc/opal-api/opal-code-update-76-77-78.rst b/doc/opal-api/opal-code-update-76-77-78.rst new file mode 100644 index 0000000..e7657d1 --- /dev/null +++ b/doc/opal-api/opal-code-update-76-77-78.rst @@ -0,0 +1,78 @@ +Code Update on FSP based machine +================================ + +There are three OPAL calls for code update on FSP based machine: + + #define OPAL_FLASH_VALIDATE 76 + #define OPAL_FLASH_MANAGE 77 + #define OPAL_FLASH_UPDATE 78 + +OPAL_FLASH_VALIDATE +------------------- + Validate new image is valid for this platform or not. We do below + validation in OPAL: + - We do below sys parameters validation to confirm inband + update is allowed. + - Platform is managed by HMC or not?. + - Code update policy (inband code update allowed?). + + - We parse candidate image header (first 4k bytes) to perform + below validations. + - Image magic number. + - Image version to confirm image is valid for this platform. + + Input: + buffer : First 4k bytes of new image + size : Input buffer size + + Output: + buffer : Output result (current and new image version details) + size : Output buffer size + result : Token to identify what will happen if update is attempted + See hw/fsp/fsp-codeupdate.h for token values. + + Return value: + Validation status + + +OPAL_FLASH_MANAGE +----------------- + Commit/Reject image. + - We can commit new image (T -> P), if system is running with T side image. + - We can reject T side image, if system is running with P side image. + + Note: + If a platform is running from a T side image when an update is to be + applied, then the platform may automatically commit the current T side + image to the P side to allow the new image to be updated to the + temporary image area. + + Input + op : Operation (1 : Commit /0 : Reject) + + Return value: + Commit operation status (0 : Success) + +OPAL_FLASH_UPDATE +------------------ + Update new image. It only sets the flag, actual update happens + during system reboot/shutdown. + + Host splits FW image to scatter/gather list and sends it to OPAL. + OPAL parse the image to get indivisual LID and passes it to FSP + via MBOX command. + + FW update flow : + - if (running side == T) + Swap P & T side + - Start code update + - Delete T side LIDs + - Write LIDs + - Code update complete + - Deep IPL + + Input + list : Real address of image scatter/gather list of the FW image + + Return value: + Update operation status (0: update requested) diff --git a/doc/opal-api/opal-code-update-76-77-78.txt b/doc/opal-api/opal-code-update-76-77-78.txt deleted file mode 100644 index e7657d1..0000000 --- a/doc/opal-api/opal-code-update-76-77-78.txt +++ /dev/null @@ -1,78 +0,0 @@ -Code Update on FSP based machine -================================ - -There are three OPAL calls for code update on FSP based machine: - - #define OPAL_FLASH_VALIDATE 76 - #define OPAL_FLASH_MANAGE 77 - #define OPAL_FLASH_UPDATE 78 - -OPAL_FLASH_VALIDATE -------------------- - Validate new image is valid for this platform or not. We do below - validation in OPAL: - - We do below sys parameters validation to confirm inband - update is allowed. - - Platform is managed by HMC or not?. - - Code update policy (inband code update allowed?). - - - We parse candidate image header (first 4k bytes) to perform - below validations. - - Image magic number. - - Image version to confirm image is valid for this platform. - - Input: - buffer : First 4k bytes of new image - size : Input buffer size - - Output: - buffer : Output result (current and new image version details) - size : Output buffer size - result : Token to identify what will happen if update is attempted - See hw/fsp/fsp-codeupdate.h for token values. - - Return value: - Validation status - - -OPAL_FLASH_MANAGE ------------------ - Commit/Reject image. - - We can commit new image (T -> P), if system is running with T side image. - - We can reject T side image, if system is running with P side image. - - Note: - If a platform is running from a T side image when an update is to be - applied, then the platform may automatically commit the current T side - image to the P side to allow the new image to be updated to the - temporary image area. - - Input - op : Operation (1 : Commit /0 : Reject) - - Return value: - Commit operation status (0 : Success) - -OPAL_FLASH_UPDATE ------------------- - Update new image. It only sets the flag, actual update happens - during system reboot/shutdown. - - Host splits FW image to scatter/gather list and sends it to OPAL. - OPAL parse the image to get indivisual LID and passes it to FSP - via MBOX command. - - FW update flow : - - if (running side == T) - Swap P & T side - - Start code update - - Delete T side LIDs - - Write LIDs - - Code update complete - - Deep IPL - - Input - list : Real address of image scatter/gather list of the FW image - - Return value: - Update operation status (0: update requested) diff --git a/doc/opal-api/opal-console-read-write-1-2.rst b/doc/opal-api/opal-console-read-write-1-2.rst new file mode 100644 index 0000000..26f9a16 --- /dev/null +++ b/doc/opal-api/opal-console-read-write-1-2.rst @@ -0,0 +1,80 @@ +OPAL Console calls +------------------ + +There are four OPAL calls relating to the OPAL console: + +#define OPAL_CONSOLE_WRITE 1 +#define OPAL_CONSOLE_READ 2 +#define OPAL_CONSOLE_WRITE_BUFFER_SPACE 25 +#define OPAL_CONSOLE_FLUSH 117 + +The OPAL console calls can support multiple consoles. Each console MUST +be represented in the device tree. + +A conforming implementation SHOULD have at least one console. It is valid +for it to simply be an in-memory buffer and only support writing. + +[TODO: details on device tree specs for console] + +OPAL_CONSOLE_WRITE +------------------ + +Parameters: + int64_t term_number + int64_t *length, + const uint8_t *buffer + +Returns: + OPAL_SUCCESS + OPAL_PARAMETER - invalid term_number + OPAL_CLOSED - console device closed + OPAL_BUSY_EVENT - unable to write any of buffer + +term_number is the terminal number as represented in the device tree. +length is a pointer to the length of buffer. + +A conformining implementation SHOULD try to NOT do partial writes, although +partial writes and not writing anything are valid. + +OPAL_CONSOLE_WRITE_BUFFER_SPACE +------------------------------- + +Parameters: + int64_t term_number + int64_t *length + +Returns: + OPAL_SUCCESS + OPAL_PARAMETER - invalid term_number + +Returns the available buffer length for OPAL_CONSOLE_WRITE in *length. +This call can be used to help work out if there is sufficient buffer +space to write your full message to the console with OPAL_CONSOLE_WRITE. + +OPAL_CONSOLE_READ +----------------- + +Parameters: + int64_t term_number + int64_t *length + uint8_t *buffer + +Returns: + OPAL_SUCCESS + OPAL_PARAMETER - invalid term_number + OPAL_CLOSED + +Use OPAL_POLL_EVENTS for how to determine + +OPAL_CONSOLE_FLUSH +------------------ + +Parameters: + int64_t term_number + +Returns: + OPAL_SUCCESS + OPAL_UNSUPPORTED - the console does not implement a flush call + OPAL_PARAMETER - invalid term_number + OPAL_PARTIAL - more to flush, call again + OPAL_BUSY - nothing was flushed this call diff --git a/doc/opal-api/opal-console-read-write-1-2.txt b/doc/opal-api/opal-console-read-write-1-2.txt deleted file mode 100644 index 26f9a16..0000000 --- a/doc/opal-api/opal-console-read-write-1-2.txt +++ /dev/null @@ -1,80 +0,0 @@ -OPAL Console calls ------------------- - -There are four OPAL calls relating to the OPAL console: - -#define OPAL_CONSOLE_WRITE 1 -#define OPAL_CONSOLE_READ 2 -#define OPAL_CONSOLE_WRITE_BUFFER_SPACE 25 -#define OPAL_CONSOLE_FLUSH 117 - -The OPAL console calls can support multiple consoles. Each console MUST -be represented in the device tree. - -A conforming implementation SHOULD have at least one console. It is valid -for it to simply be an in-memory buffer and only support writing. - -[TODO: details on device tree specs for console] - -OPAL_CONSOLE_WRITE ------------------- - -Parameters: - int64_t term_number - int64_t *length, - const uint8_t *buffer - -Returns: - OPAL_SUCCESS - OPAL_PARAMETER - invalid term_number - OPAL_CLOSED - console device closed - OPAL_BUSY_EVENT - unable to write any of buffer - -term_number is the terminal number as represented in the device tree. -length is a pointer to the length of buffer. - -A conformining implementation SHOULD try to NOT do partial writes, although -partial writes and not writing anything are valid. - -OPAL_CONSOLE_WRITE_BUFFER_SPACE -------------------------------- - -Parameters: - int64_t term_number - int64_t *length - -Returns: - OPAL_SUCCESS - OPAL_PARAMETER - invalid term_number - -Returns the available buffer length for OPAL_CONSOLE_WRITE in *length. -This call can be used to help work out if there is sufficient buffer -space to write your full message to the console with OPAL_CONSOLE_WRITE. - -OPAL_CONSOLE_READ ------------------ - -Parameters: - int64_t term_number - int64_t *length - uint8_t *buffer - -Returns: - OPAL_SUCCESS - OPAL_PARAMETER - invalid term_number - OPAL_CLOSED - -Use OPAL_POLL_EVENTS for how to determine - -OPAL_CONSOLE_FLUSH ------------------- - -Parameters: - int64_t term_number - -Returns: - OPAL_SUCCESS - OPAL_UNSUPPORTED - the console does not implement a flush call - OPAL_PARAMETER - invalid term_number - OPAL_PARTIAL - more to flush, call again - OPAL_BUSY - nothing was flushed this call diff --git a/doc/opal-api/opal-flash-110-111-112.rst b/doc/opal-api/opal-flash-110-111-112.rst new file mode 100644 index 0000000..860172b --- /dev/null +++ b/doc/opal-api/opal-flash-110-111-112.rst @@ -0,0 +1,72 @@ + +OPAL Flash calls +---------------- + +There are three OPAL calls for interacting with flash devices: + + #define OPAL_FLASH_READ 110 + #define OPAL_FLASH_WRITE 111 + #define OPAL_FLASH_ERASE 112 + +Multiple flash devices are supported by OPAL - each of these calls takes an id +parameter, which much match an ID found in the corresponding ibm,opal/flash@n +device tree node. See doc/device-tree/ibm,opal/flash.txt for details of +the device tree bindings. + +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 +opal_async_completion message will be sent (with the appropriate token +argument) when the operation completes. + +All calls share the same return values: + + OPAL_ASYNC_COMPLETION - operation started, an async completion will + be triggered with the @token argument + OPAL_PARAMETER - invalid flash id + OPAL_PARAMETER - invalid size or offset (alignment, or access beyond end + of device) + OPAL_BUSY - flash in use + OPAL_HARDWARE - error accessing flash device + +OPAL_FLASH_READ +--------------- + +Parameters: + uint64_t id + uint64_t offset + uint64_t buffer + 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 +--------------- + +Parameters: + 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 +--------------- + +Parameters: + uint64_t id + uint64_t offset + uint64_t buffer + 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 +token when completed. + diff --git a/doc/opal-api/opal-flash-110-111-112.txt b/doc/opal-api/opal-flash-110-111-112.txt deleted file mode 100644 index 860172b..0000000 --- a/doc/opal-api/opal-flash-110-111-112.txt +++ /dev/null @@ -1,72 +0,0 @@ - -OPAL Flash calls ----------------- - -There are three OPAL calls for interacting with flash devices: - - #define OPAL_FLASH_READ 110 - #define OPAL_FLASH_WRITE 111 - #define OPAL_FLASH_ERASE 112 - -Multiple flash devices are supported by OPAL - each of these calls takes an id -parameter, which much match an ID found in the corresponding ibm,opal/flash@n -device tree node. See doc/device-tree/ibm,opal/flash.txt for details of -the device tree bindings. - -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 -opal_async_completion message will be sent (with the appropriate token -argument) when the operation completes. - -All calls share the same return values: - - OPAL_ASYNC_COMPLETION - operation started, an async completion will - be triggered with the @token argument - OPAL_PARAMETER - invalid flash id - OPAL_PARAMETER - invalid size or offset (alignment, or access beyond end - of device) - OPAL_BUSY - flash in use - OPAL_HARDWARE - error accessing flash device - -OPAL_FLASH_READ ---------------- - -Parameters: - uint64_t id - uint64_t offset - uint64_t buffer - 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 ---------------- - -Parameters: - 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 ---------------- - -Parameters: - uint64_t id - uint64_t offset - uint64_t buffer - 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 -token when completed. - diff --git a/doc/opal-api/opal-get-device-tree-118.rst b/doc/opal-api/opal-get-device-tree-118.rst new file mode 100644 index 0000000..235a321 --- /dev/null +++ b/doc/opal-api/opal-get-device-tree-118.rst @@ -0,0 +1,24 @@ +OPAL_GET_DEVICE_TREE +-------------------- + +Get device sub-tree + +Parameters: + uint32_t phandle: root device node phandle of the device sub-tree + uint64_t buf: FDT blob buffer or NULL + uint64_t len: length of the FDT blob buffer + +Calling: + +Retrieve device sub-tree. The root node's phandle is identified by @phandle. +The typical use is for the kernel to update its device tree following a change +in hardware (e.g. PCI hotplug). + +Return Codes: + +FDT blob size - returned FDT blob buffer size when @buf is NULL +OPAL_SUCCESS - FDT blob is created successfully +OPAL_PARAMETER - invalid argument @phandle or @len +OPAL_INTERNAL_ERROR - failure creating FDT blob when calculating its size +OPAL_NO_MEM - not enough room in buffer for device sub-tree +OPAL_EMPTY - failure creating FDT blob diff --git a/doc/opal-api/opal-get-device-tree-118.txt b/doc/opal-api/opal-get-device-tree-118.txt deleted file mode 100644 index 235a321..0000000 --- a/doc/opal-api/opal-get-device-tree-118.txt +++ /dev/null @@ -1,24 +0,0 @@ -OPAL_GET_DEVICE_TREE --------------------- - -Get device sub-tree - -Parameters: - uint32_t phandle: root device node phandle of the device sub-tree - uint64_t buf: FDT blob buffer or NULL - uint64_t len: length of the FDT blob buffer - -Calling: - -Retrieve device sub-tree. The root node's phandle is identified by @phandle. -The typical use is for the kernel to update its device tree following a change -in hardware (e.g. PCI hotplug). - -Return Codes: - -FDT blob size - returned FDT blob buffer size when @buf is NULL -OPAL_SUCCESS - FDT blob is created successfully -OPAL_PARAMETER - invalid argument @phandle or @len -OPAL_INTERNAL_ERROR - failure creating FDT blob when calculating its size -OPAL_NO_MEM - not enough room in buffer for device sub-tree -OPAL_EMPTY - failure creating FDT blob diff --git a/doc/opal-api/opal-get-msg-85.rst b/doc/opal-api/opal-get-msg-85.rst new file mode 100644 index 0000000..fa839a8 --- /dev/null +++ b/doc/opal-api/opal-get-msg-85.rst @@ -0,0 +1,43 @@ +OPAL_GET_MSG +------------ + +OPAL_GET_MSG will get the next pending OPAL Message (see +opal-messages.txt). + +Parameters: + buffer to copy message into + sizeof buffer to copy message into + +The maximum size of an opal message is specified in the device tree passed +to the host OS: + + ibm,opal { + opal-msg-size = <0x48>; + } + +It is ALWAYS at least 72 bytes. In the future, OPAL may have messages larger +than 72 bytes. Naturally, a HOST OS will only be able to interpret these +if it correctly uses opal-msg-size. Any OPAL message > 72 bytes, a host OS +may safely ignore. + +A host OS *SHOULD* always supply a buffer to OPAL_GET_MSG of either 72 +bytes or opal-msg-size. It MUST NOT supply a buffer of < 72 bytes. + + +Return values: + +OPAL_RESOURCE - no available message. + +OPAL_PARAMETER - buffer is NULL or size is < 72 bytes. + If buffer size < 72 bytes, the message will NOT be discarded + by OPAL. + +OPAL_PARTIAL - If pending opal message is greater than supplied buffer. + In this case the message is *DISCARDED* by OPAL. + This is to keep compatibility with host Operating Systems + with a hard coded opal-msg-size of 72 bytes. + NOT CURRENTLY IMPLEMENTED. Specified so that host OS can + prepare for the possible future with either a sensible + error message or by gracefully ignoring such OPAL messages. + +OPAL_SUCCESS - message successfully copied to buffer. diff --git a/doc/opal-api/opal-get-msg-85.txt b/doc/opal-api/opal-get-msg-85.txt deleted file mode 100644 index fa839a8..0000000 --- a/doc/opal-api/opal-get-msg-85.txt +++ /dev/null @@ -1,43 +0,0 @@ -OPAL_GET_MSG ------------- - -OPAL_GET_MSG will get the next pending OPAL Message (see -opal-messages.txt). - -Parameters: - buffer to copy message into - sizeof buffer to copy message into - -The maximum size of an opal message is specified in the device tree passed -to the host OS: - - ibm,opal { - opal-msg-size = <0x48>; - } - -It is ALWAYS at least 72 bytes. In the future, OPAL may have messages larger -than 72 bytes. Naturally, a HOST OS will only be able to interpret these -if it correctly uses opal-msg-size. Any OPAL message > 72 bytes, a host OS -may safely ignore. - -A host OS *SHOULD* always supply a buffer to OPAL_GET_MSG of either 72 -bytes or opal-msg-size. It MUST NOT supply a buffer of < 72 bytes. - - -Return values: - -OPAL_RESOURCE - no available message. - -OPAL_PARAMETER - buffer is NULL or size is < 72 bytes. - If buffer size < 72 bytes, the message will NOT be discarded - by OPAL. - -OPAL_PARTIAL - If pending opal message is greater than supplied buffer. - In this case the message is *DISCARDED* by OPAL. - This is to keep compatibility with host Operating Systems - with a hard coded opal-msg-size of 72 bytes. - NOT CURRENTLY IMPLEMENTED. Specified so that host OS can - prepare for the possible future with either a sensible - error message or by gracefully ignoring such OPAL messages. - -OPAL_SUCCESS - message successfully copied to buffer. diff --git a/doc/opal-api/opal-get-msi-39-40.rst b/doc/opal-api/opal-get-msi-39-40.rst new file mode 100644 index 0000000..dbc809f --- /dev/null +++ b/doc/opal-api/opal-get-msi-39-40.rst @@ -0,0 +1,46 @@ +OPAL_GET_MSI_32 and OPAL_GET_MSI_64 +----------------------------------- + +#define OPAL_GET_MSI_32 39 +#define OPAL_GET_MSI_64 40 + +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. + +OPAL PHBs encode MVE and XIVE specifiers in MSI DMA and message data values. +The host calls these functions to determine the PHB MSI DMA address and message +data to program into a PE PCIE function for a particular MVE and XIVE. The +msi_address parameter returns the MSI DMA address and the msi_data parameter +returns the MSI DMA message data value the PE uses to signal that interrupt. + + The phb_id parameter is the value from the PHB node ibm,opal-phbid + property. + + The mve_number is the index of an MVE used to authorize this PE to this + MSI. For ibm,opal-ioda2 PHBs, the MVE number argument is ignored. + + The xive_number is the index of an XIVE that corresponds to a particular + DMA address and message data value this PE will signal as an MSI ro MSI-X. + + The msi_range parameter specifies the number of MSIs associated with the + in put MVE and XIVE, primarily for MSI-conventional Multiple Message + Enable > 1 MSI. MSI requires consecutive MSIs per MSI address, and each + MSI DMA address must be unique for any given consecutive power of 2 set + of 32 message data values,. which in turn select particular PHB XIVEs. + This value must be a power of 2 value in the range of 0 to 32. OPAL + returns opal_parameter for values outside of this range. + +For MSI conventional, the MSI address and message data returned apply to a +power of 2 sequential set of XIVRs starting from the xive_number for the +power of 2 msi_range input argument. The message data returned represents the +power of 2 aligned starting message data value of the first interrupt number +in that sequential range. Valid msi_range input values are from 1 to 32. +Non-power of 2 values result in a return code of opal_PARAMETER . + +An msi_range value of 0 or 1 signifies that OPAL should return the message +data and message address for exactly one MSI specified by the input XIVE +number. For MSI conventional, the host should specify either a value of 0 or 1, +for an MSI Capability MME value of 1 MSI. For MSI-X XIVRs, the host should +specify a value of '1' for the msi_range argument and call this function for +each MSI-X uniquely. diff --git a/doc/opal-api/opal-get-msi-39-40.txt b/doc/opal-api/opal-get-msi-39-40.txt deleted file mode 100644 index dbc809f..0000000 --- a/doc/opal-api/opal-get-msi-39-40.txt +++ /dev/null @@ -1,46 +0,0 @@ -OPAL_GET_MSI_32 and OPAL_GET_MSI_64 ------------------------------------ - -#define OPAL_GET_MSI_32 39 -#define OPAL_GET_MSI_64 40 - -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. - -OPAL PHBs encode MVE and XIVE specifiers in MSI DMA and message data values. -The host calls these functions to determine the PHB MSI DMA address and message -data to program into a PE PCIE function for a particular MVE and XIVE. The -msi_address parameter returns the MSI DMA address and the msi_data parameter -returns the MSI DMA message data value the PE uses to signal that interrupt. - - The phb_id parameter is the value from the PHB node ibm,opal-phbid - property. - - The mve_number is the index of an MVE used to authorize this PE to this - MSI. For ibm,opal-ioda2 PHBs, the MVE number argument is ignored. - - The xive_number is the index of an XIVE that corresponds to a particular - DMA address and message data value this PE will signal as an MSI ro MSI-X. - - The msi_range parameter specifies the number of MSIs associated with the - in put MVE and XIVE, primarily for MSI-conventional Multiple Message - Enable > 1 MSI. MSI requires consecutive MSIs per MSI address, and each - MSI DMA address must be unique for any given consecutive power of 2 set - of 32 message data values,. which in turn select particular PHB XIVEs. - This value must be a power of 2 value in the range of 0 to 32. OPAL - returns opal_parameter for values outside of this range. - -For MSI conventional, the MSI address and message data returned apply to a -power of 2 sequential set of XIVRs starting from the xive_number for the -power of 2 msi_range input argument. The message data returned represents the -power of 2 aligned starting message data value of the first interrupt number -in that sequential range. Valid msi_range input values are from 1 to 32. -Non-power of 2 values result in a return code of opal_PARAMETER . - -An msi_range value of 0 or 1 signifies that OPAL should return the message -data and message address for exactly one MSI specified by the input XIVE -number. For MSI conventional, the host should specify either a value of 0 or 1, -for an MSI Capability MME value of 1 MSI. For MSI-X XIVRs, the host should -specify a value of '1' for the msi_range argument and call this function for -each MSI-X uniquely. diff --git a/doc/opal-api/opal-get-xive-20.rst b/doc/opal-api/opal-get-xive-20.rst new file mode 100644 index 0000000..2a83cc8 --- /dev/null +++ b/doc/opal-api/opal-get-xive-20.rst @@ -0,0 +1,25 @@ +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 POWER XIVE server and priority +values currently set in a PHB XIVE. + + The phb_id parameter is the value from the PHB node ibm,opal-phbid + property. + + The xive_number is the index of an XIVE that corresponds to a particular + interrupt + + the server_number returns the server (processor) that is set in this XIVE + + 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. + diff --git a/doc/opal-api/opal-get-xive-20.txt b/doc/opal-api/opal-get-xive-20.txt deleted file mode 100644 index 2a83cc8..0000000 --- a/doc/opal-api/opal-get-xive-20.txt +++ /dev/null @@ -1,25 +0,0 @@ -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 POWER XIVE server and priority -values currently set in a PHB XIVE. - - The phb_id parameter is the value from the PHB node ibm,opal-phbid - property. - - The xive_number is the index of an XIVE that corresponds to a particular - interrupt - - the server_number returns the server (processor) that is set in this XIVE - - 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. - diff --git a/doc/opal-api/opal-handle-interrupt.rst b/doc/opal-api/opal-handle-interrupt.rst new file mode 100644 index 0000000..efae29e --- /dev/null +++ b/doc/opal-api/opal-handle-interrupt.rst @@ -0,0 +1,26 @@ +OPAL_HANDLE_INTERRUPT +--------------------- + +The host OS must pass all interrupts in "ibm,opal/opal-interrupts" in the +device tree to OPAL. + +An example dt snippet is: + + ibm,opal { + ... + opal-interrupts = <0x10 0x11 0x12 0x13 0x14 0x20010 0x20011 0x20012 0x20013 0x20014 0xffe 0xfff 0x17fe 0x17ff 0x2ffe 0x2fff 0x37fe 0x37ff 0x20ffe 0x20fff 0x217fe 0x217ff 0x22ffe 0x22fff 0x237fe 0x237ff>; + } + +When the host OS gets any of these interrupts, it must call +OPAL_HANDLE_INTERRUPT. + +The OPAL_HANDLE_INTERRUPT call takes two parameters, one input and one output. + +uint32_t isn - the interrupt + +uint64_t *outstanding_event_mask - returns outstanding events for host + OS to handle + +The host OS should then handle any outstanding events. + +See opal-poll-events.txt for documentation on events. diff --git a/doc/opal-api/opal-handle-interrupt.txt b/doc/opal-api/opal-handle-interrupt.txt deleted file mode 100644 index efae29e..0000000 --- a/doc/opal-api/opal-handle-interrupt.txt +++ /dev/null @@ -1,26 +0,0 @@ -OPAL_HANDLE_INTERRUPT ---------------------- - -The host OS must pass all interrupts in "ibm,opal/opal-interrupts" in the -device tree to OPAL. - -An example dt snippet is: - - ibm,opal { - ... - opal-interrupts = <0x10 0x11 0x12 0x13 0x14 0x20010 0x20011 0x20012 0x20013 0x20014 0xffe 0xfff 0x17fe 0x17ff 0x2ffe 0x2fff 0x37fe 0x37ff 0x20ffe 0x20fff 0x217fe 0x217ff 0x22ffe 0x22fff 0x237fe 0x237ff>; - } - -When the host OS gets any of these interrupts, it must call -OPAL_HANDLE_INTERRUPT. - -The OPAL_HANDLE_INTERRUPT call takes two parameters, one input and one output. - -uint32_t isn - the interrupt - -uint64_t *outstanding_event_mask - returns outstanding events for host - OS to handle - -The host OS should then handle any outstanding events. - -See opal-poll-events.txt for documentation on events. diff --git a/doc/opal-api/opal-int-eoi-124.rst b/doc/opal-api/opal-int-eoi-124.rst new file mode 100644 index 0000000..17e4eff --- /dev/null +++ b/doc/opal-api/opal-int-eoi-124.rst @@ -0,0 +1,20 @@ +OPAL_INT_EOI +------------ + +static int64_t opal_xive_eoi(uint32_t xirr) + +Not yet implemented. + +Modelled on the H_EOI PAPR call. + +This can return a positive value, which means more interrupts +are queued for that CPU/priority and must be fetched as the XIVE is not +guaranteed to assert the CPU external interrupt line again until the +pending queue for the current priority has been emptied. + +For P9 and above systems where host doesn't know about interrupt controller. +An OS can instead make OPAL calls for XICS emulation. + +For an OS to use this OPAL call, an "ibm,opal-intc" compatible device must +exist in the device tree. If OPAL does not create such a device, the host +OS MUST NOT use this call. diff --git a/doc/opal-api/opal-int-eoi-124.txt b/doc/opal-api/opal-int-eoi-124.txt deleted file mode 100644 index 17e4eff..0000000 --- a/doc/opal-api/opal-int-eoi-124.txt +++ /dev/null @@ -1,20 +0,0 @@ -OPAL_INT_EOI ------------- - -static int64_t opal_xive_eoi(uint32_t xirr) - -Not yet implemented. - -Modelled on the H_EOI PAPR call. - -This can return a positive value, which means more interrupts -are queued for that CPU/priority and must be fetched as the XIVE is not -guaranteed to assert the CPU external interrupt line again until the -pending queue for the current priority has been emptied. - -For P9 and above systems where host doesn't know about interrupt controller. -An OS can instead make OPAL calls for XICS emulation. - -For an OS to use this OPAL call, an "ibm,opal-intc" compatible device must -exist in the device tree. If OPAL does not create such a device, the host -OS MUST NOT use this call. diff --git a/doc/opal-api/opal-int-get-xirr-122.rst b/doc/opal-api/opal-int-get-xirr-122.rst new file mode 100644 index 0000000..efa86d5 --- /dev/null +++ b/doc/opal-api/opal-int-get-xirr-122.rst @@ -0,0 +1,15 @@ +OPAL_INT_GET_XIRR +----------------- + +int64_t opal_xive_get_xirr(uint32_t *out_xirr, bool just_poll) + +Not yet implemented. + +Modelled on the PAPR call. + +For P9 and above systems where host doesn't know about interrupt controller. +An OS can instead make OPAL calls for XICS emulation. + +For an OS to use this OPAL call, an "ibm,opal-intc" compatible device must +exist in the device tree. If OPAL does not create such a device, the host +OS MUST NOT use this call. diff --git a/doc/opal-api/opal-int-get-xirr-122.txt b/doc/opal-api/opal-int-get-xirr-122.txt deleted file mode 100644 index efa86d5..0000000 --- a/doc/opal-api/opal-int-get-xirr-122.txt +++ /dev/null @@ -1,15 +0,0 @@ -OPAL_INT_GET_XIRR ------------------ - -int64_t opal_xive_get_xirr(uint32_t *out_xirr, bool just_poll) - -Not yet implemented. - -Modelled on the PAPR call. - -For P9 and above systems where host doesn't know about interrupt controller. -An OS can instead make OPAL calls for XICS emulation. - -For an OS to use this OPAL call, an "ibm,opal-intc" compatible device must -exist in the device tree. If OPAL does not create such a device, the host -OS MUST NOT use this call. diff --git a/doc/opal-api/opal-int-set-cppr-123.rst b/doc/opal-api/opal-int-set-cppr-123.rst new file mode 100644 index 0000000..b6858c9 --- /dev/null +++ b/doc/opal-api/opal-int-set-cppr-123.rst @@ -0,0 +1,16 @@ +OPAL_INT_SET_CPPR +----------------- + +static int64_t opal_xive_set_cppr(uint8_t cppr) + + +Not yet implemented. + +Modelled on the H_CPPR PAPR call. + +For P9 and above systems where host doesn't know about interrupt controller. +An OS can instead make OPAL calls for XICS emulation. + +For an OS to use this OPAL call, an "ibm,opal-intc" compatible device must +exist in the device tree. If OPAL does not create such a device, the host +OS MUST NOT use this call. diff --git a/doc/opal-api/opal-int-set-cppr-123.txt b/doc/opal-api/opal-int-set-cppr-123.txt deleted file mode 100644 index b6858c9..0000000 --- a/doc/opal-api/opal-int-set-cppr-123.txt +++ /dev/null @@ -1,16 +0,0 @@ -OPAL_INT_SET_CPPR ------------------ - -static int64_t opal_xive_set_cppr(uint8_t cppr) - - -Not yet implemented. - -Modelled on the H_CPPR PAPR call. - -For P9 and above systems where host doesn't know about interrupt controller. -An OS can instead make OPAL calls for XICS emulation. - -For an OS to use this OPAL call, an "ibm,opal-intc" compatible device must -exist in the device tree. If OPAL does not create such a device, the host -OS MUST NOT use this call. diff --git a/doc/opal-api/opal-int-set-mfrr-125.rst b/doc/opal-api/opal-int-set-mfrr-125.rst new file mode 100644 index 0000000..64a7506 --- /dev/null +++ b/doc/opal-api/opal-int-set-mfrr-125.rst @@ -0,0 +1,15 @@ +OPAL_INT_SET_MFRR +----------------- + +static int64_t opal_xive_set_mfrr(uint32_t cpu, uint8_t mfrr) + +Not yet implemented. + +Modelled on the H_IPI PAPR call. + +For P9 and above systems where host doesn't know about interrupt controller. +An OS can instead make OPAL calls for XICS emulation. + +For an OS to use this OPAL call, an "ibm,opal-intc" compatible device must +exist in the device tree. If OPAL does not create such a device, the host +OS MUST NOT use this call. diff --git a/doc/opal-api/opal-int-set-mfrr-125.txt b/doc/opal-api/opal-int-set-mfrr-125.txt deleted file mode 100644 index 64a7506..0000000 --- a/doc/opal-api/opal-int-set-mfrr-125.txt +++ /dev/null @@ -1,15 +0,0 @@ -OPAL_INT_SET_MFRR ------------------ - -static int64_t opal_xive_set_mfrr(uint32_t cpu, uint8_t mfrr) - -Not yet implemented. - -Modelled on the H_IPI PAPR call. - -For P9 and above systems where host doesn't know about interrupt controller. -An OS can instead make OPAL calls for XICS emulation. - -For an OS to use this OPAL call, an "ibm,opal-intc" compatible device must -exist in the device tree. If OPAL does not create such a device, the host -OS MUST NOT use this call. diff --git a/doc/opal-api/opal-invalid-call--1.rst b/doc/opal-api/opal-invalid-call--1.rst new file mode 100644 index 0000000..affdbda --- /dev/null +++ b/doc/opal-api/opal-invalid-call--1.rst @@ -0,0 +1,6 @@ +OPAL_INVALID_CALL +----------------- + +An OPAL call of -1 will always return OPAL_PARAMETER. It is always ivalid. + +It exists purely for testing. diff --git a/doc/opal-api/opal-invalid-call--1.txt b/doc/opal-api/opal-invalid-call--1.txt deleted file mode 100644 index affdbda..0000000 --- a/doc/opal-api/opal-invalid-call--1.txt +++ /dev/null @@ -1,6 +0,0 @@ -OPAL_INVALID_CALL ------------------ - -An OPAL call of -1 will always return OPAL_PARAMETER. It is always ivalid. - -It exists purely for testing. diff --git a/doc/opal-api/opal-led-get-set-114-115.rst b/doc/opal-api/opal-led-get-set-114-115.rst new file mode 100644 index 0000000..1d90ea4 --- /dev/null +++ b/doc/opal-api/opal-led-get-set-114-115.rst @@ -0,0 +1,55 @@ +Service Indicators (LEDS) +------------------------- + +The service indicator is one element of an overall hardware service strategy +where end user simplicity is a high priority. The goal is system firmware or +operating system code to isolate hardware failures to the failing FRU and +automatically activate the fault indicator associated with the failing FRU. +The end user then needs only to look for the FRU with the active fault +indicator to know which part to replace. + +Different types of indicators handled by LED code: + - System attention indicator (Check log indicator) + Indicates there is a problem with the system that needs attention. + - Identify + Helps the user locate/identify a particular FRU or resource in the + system. + - Fault + Indicates there is a problem with the FRU or resource at the + location with which the indicator is associated. + + +LED Design: +----------- + When it comes to implementation we can classify LEDs into two + categories: + 1 - Hypervisor (OPAL) controlled LEDs (All identify & fault indicators) + During boot, we read/cache these LED details in OPAL (location code, + state, etc). We use cached data to serve read request from FSP/Host. + And we use SPCN passthrough MBOX command to update these LED state. + + 2 - Service processor (FSP) controlled LEDs (System Attention Indicator) + During boot, we read/cache this LED info using MBOX command. Later + anytime FSP updates this LED, it sends update system parameter + notification MBOX command. We use that data to update cached data. + LED update request is sent via set/reset attn MBOX command. + + LED update request: + Both FSP and Host will send LED update requests. We have to serialize + SPCN passthrough command. Hence we maintain local queue. + +Note: + - For more information regarding service indicator refer to PAPR spec + (Service Indicators chapter). + +There are two OPAL calls relating to LED operations. + +OPAL_LEDS_GET_INDICATOR +----------------------- + Returns LED state for the given location code. + +OPAL_LEDS_SET_INDICATOR +----------------------- + Sets LED state for the given location code. + +See hw/fsp/fsp-leds.c for more deatails. diff --git a/doc/opal-api/opal-led-get-set-114-115.txt b/doc/opal-api/opal-led-get-set-114-115.txt deleted file mode 100644 index 1d90ea4..0000000 --- a/doc/opal-api/opal-led-get-set-114-115.txt +++ /dev/null @@ -1,55 +0,0 @@ -Service Indicators (LEDS) -------------------------- - -The service indicator is one element of an overall hardware service strategy -where end user simplicity is a high priority. The goal is system firmware or -operating system code to isolate hardware failures to the failing FRU and -automatically activate the fault indicator associated with the failing FRU. -The end user then needs only to look for the FRU with the active fault -indicator to know which part to replace. - -Different types of indicators handled by LED code: - - System attention indicator (Check log indicator) - Indicates there is a problem with the system that needs attention. - - Identify - Helps the user locate/identify a particular FRU or resource in the - system. - - Fault - Indicates there is a problem with the FRU or resource at the - location with which the indicator is associated. - - -LED Design: ------------ - When it comes to implementation we can classify LEDs into two - categories: - 1 - Hypervisor (OPAL) controlled LEDs (All identify & fault indicators) - During boot, we read/cache these LED details in OPAL (location code, - state, etc). We use cached data to serve read request from FSP/Host. - And we use SPCN passthrough MBOX command to update these LED state. - - 2 - Service processor (FSP) controlled LEDs (System Attention Indicator) - During boot, we read/cache this LED info using MBOX command. Later - anytime FSP updates this LED, it sends update system parameter - notification MBOX command. We use that data to update cached data. - LED update request is sent via set/reset attn MBOX command. - - LED update request: - Both FSP and Host will send LED update requests. We have to serialize - SPCN passthrough command. Hence we maintain local queue. - -Note: - - For more information regarding service indicator refer to PAPR spec - (Service Indicators chapter). - -There are two OPAL calls relating to LED operations. - -OPAL_LEDS_GET_INDICATOR ------------------------ - Returns LED state for the given location code. - -OPAL_LEDS_SET_INDICATOR ------------------------ - Sets LED state for the given location code. - -See hw/fsp/fsp-leds.c for more deatails. diff --git a/doc/opal-api/opal-messages.rst b/doc/opal-api/opal-messages.rst new file mode 100644 index 0000000..00a28e5 --- /dev/null +++ b/doc/opal-api/opal-messages.rst @@ -0,0 +1,213 @@ +OAPL_MESSAGE +============ + +The host OS can use OPAL_GET_MSG to retrive messages queued by OPAL. The +messages are defined by enum opal_msg_type. The host is notified of there +being messages to be consumed by the OPAL_EVENT_MSG_PENDING bit being set. + +An opal_msg is: +struct opal_msg { + __be32 msg_type; + __be32 reserved; + __be64 params[8]; +}; + +The data structure is ALWAYS at least this size (4+4+8*8 = 72 bytes). Some +messages define fewer than eight parameters. For messages that do not +define all eight parameters, the value in the undefined parameters is +undefined, although can safely be memcpy()d or otherwise moved. + +In the device tree, there's an opal-msg-size property of the OPAL node that +says the size of a struct opal-msg. In the future, OPAL may support larger +messages. See OPAL_GET_MESSAGE documentation for details. + + ibm,opal { + opal-msg-size = <0x48>; + } + + +OPAL_MSG_ASYNC_COMP +------------------- + +params[0] = token +params[1] = rc + +Additional parameters are function-specific. + +OPAL_MSG_MEM_ERR +---------------- + +OPAL_MSG_EPOW +------------- + +Used by OPAL to issue environmental and power warnings to host OS for +conditions requiring an earlier poweroff. A few examples of these are high +ambient temperature or system running on UPS power with low UPS battery. +Host OS can query OPAL via GET_EPOW_STATUS API to obtain information about +EPOW conditions present. Refer include/opal-api.h for description of +all supported EPOW events. OPAL_SYSPOWER_CHNG, OPAL_SYSPOWER_FAIL and +OPAL_SYSPOWER_INC events don't require system poweroff. + +Host OS should look for 'ibm,opal-v3-epow' string as compatible property +for 'epow' node under OPAL device-tree to determine epow support. + +OPAL_MSG_SHUTDOWN +----------------- + +Used by OPAL to inform the host OS it must imitate a graceful shutdown. Uses +the first parameter to indicate weather the system is going down for shutdown +or a reboot. + +params[0] = 0x01 reboot, 0x00 shutdown + +OPAL_MSG_HMI_EVT +---------------- + +Used by OPAL to sends the OPAL HMI Event to the host OS that reports a +summary of HMI error and whether it was successfully recovered or not. + +HMI is a Hypervisor Maintenance Interrupt usually reports error related +to processor recovery/checkstop, NX checkstop and Timer facility. Hypervisor +then takes this opportunity to analyze and recover from some of these errors. +Hypervisor takes assistance from OPAL layer to handle and recover from +HMI. After handling HMI, OPAL layer sends the summary of error report and +status of recovery action using HMI event structure shown below. + +The HMI event structure uses version numbering to allow future enhancement +to accommodate additional members. The version start from V1 onward. +Version 0 is invalid version and unsupported. + +The current version of HMI event structure V2 and is backward compatible +to V1 version. + +Notes: +- When adding new structure to the union in future, the version number + must be bumped. +- All future versions must be backward compatible to all its older versions. +- Size of this structure should not exceed that of struct opal_msg. + +struct OpalHMIEvent { + uint8_t version; /* 0x00 */ + uint8_t severity; /* 0x01 */ + uint8_t type; /* 0x02 */ + uint8_t disposition; /* 0x03 */ + uint8_t reserved_1[4]; /* 0x04 */ + + __be64 hmer; + /* TFMR register. Valid only for TFAC and TFMR_PARITY error type. */ + __be64 tfmr; + + /* version 2 and later */ + union { + /* + * checkstop info (Core/NX). + * Valid for OpalHMI_ERROR_MALFUNC_ALERT. + */ + struct { + uint8_t xstop_type; /* enum OpalHMI_XstopType */ + uint8_t reserved_1[3]; + __be32 xstop_reason; + union { + __be32 pir; /* for CHECKSTOP_TYPE_CORE */ + __be32 chip_id; /* for CHECKSTOP_TYPE_NX */ + } u; + } xstop_error; + } u; +}; + + +OPAL_MSG_DPO +------------ + +Delayed poweroff where OPAL informs host OS that a poweroff has been +requested and a forced shutdown will happen in future. Host OS can use +OPAL_GET_DPO_STATUS API to query OPAL the number of seconds remaining +before a forced poweroff will occur. + +OPAL_MSG_PRD +------------ + +This message is a OPAL-to-HBRT notification, and contains a +struct opal_prd_msg: + + enum opal_prd_msg_type { + OPAL_PRD_MSG_TYPE_INIT = 0, /* HBRT --> OPAL */ + OPAL_PRD_MSG_TYPE_FINI, /* HBRT --> OPAL */ + OPAL_PRD_MSG_TYPE_ATTN, /* HBRT <-- OPAL */ + OPAL_PRD_MSG_TYPE_ATTN_ACK, /* HBRT --> OPAL */ + OPAL_PRD_MSG_TYPE_OCC_ERROR, /* HBRT <-- OPAL */ + OPAL_PRD_MSG_TYPE_OCC_RESET, /* HBRT <-- OPAL */ + }; + + struct opal_prd_msg { + uint8_t type; + uint8_t pad[3]; + __be32 token; + union { + struct { + __be64 version; + __be64 ipoll; + } init; + struct { + __be64 proc; + __be64 ipoll_status; + __be64 ipoll_mask; + } attn; + struct { + __be64 proc; + __be64 ipoll_ack; + } attn_ack; + struct { + __be64 chip; + } occ_error; + struct { + __be64 chip; + } occ_reset; + }; + }; + +Responses from the kernel use the same message format, but are passed +through the opal_prd_msg call. + +OPAL_MSG_OCC +------------ + +This is used by OPAL to inform host about OCC events like OCC reset, +OCC load and throttle status change by OCC which can indicate the +host the reason for frequency throttling/unthrottling. + +#define OCC_RESET 0 +#define OCC_LOAD 1 +#define OCC_THROTTLE 2 +#define OCC_MAX_THROTTLE_STATUS 5 +/* + * struct opal_occ_msg: + * type: OCC_RESET, OCC_LOAD, OCC_THROTTLE + * chip: chip id + * throttle status: Indicates the reason why OCC may have limited + * the max Pstate of the chip. + * 0x00 = No throttle + * 0x01 = Power Cap + * 0x02 = Processor Over Temperature + * 0x03 = Power Supply Failure (currently not used) + * 0x04 = Over current (currently not used) + * 0x05 = OCC Reset (not reliable as some failures will not allow for + * OCC to update throttle status) + */ +struct opal_occ_msg { + __be64 type; + __be64 chip; + __be64 throttle_status; +}; + +Host should read opal_occ_msg.chip and opal_occ_msg.throttle_status +only when opal_occ_msg.type = OCC_THROTTLE. +If host receives OCC_THROTTLE after an OCC_RESET then this throttle +message will have a special meaning which indicates that all the OCCs +have become active after a reset. In such cases opal_occ_msg.chip and +opal_occ_msg.throttle_status will be set to 0 and host should not use +these values. + +If opal_occ_msg.type > 2 then host should ignore the message for now, +new events can be defined for opal_occ_msg.type in the future versions +of OPAL. diff --git a/doc/opal-api/opal-messages.txt b/doc/opal-api/opal-messages.txt deleted file mode 100644 index 00a28e5..0000000 --- a/doc/opal-api/opal-messages.txt +++ /dev/null @@ -1,213 +0,0 @@ -OAPL_MESSAGE -============ - -The host OS can use OPAL_GET_MSG to retrive messages queued by OPAL. The -messages are defined by enum opal_msg_type. The host is notified of there -being messages to be consumed by the OPAL_EVENT_MSG_PENDING bit being set. - -An opal_msg is: -struct opal_msg { - __be32 msg_type; - __be32 reserved; - __be64 params[8]; -}; - -The data structure is ALWAYS at least this size (4+4+8*8 = 72 bytes). Some -messages define fewer than eight parameters. For messages that do not -define all eight parameters, the value in the undefined parameters is -undefined, although can safely be memcpy()d or otherwise moved. - -In the device tree, there's an opal-msg-size property of the OPAL node that -says the size of a struct opal-msg. In the future, OPAL may support larger -messages. See OPAL_GET_MESSAGE documentation for details. - - ibm,opal { - opal-msg-size = <0x48>; - } - - -OPAL_MSG_ASYNC_COMP -------------------- - -params[0] = token -params[1] = rc - -Additional parameters are function-specific. - -OPAL_MSG_MEM_ERR ----------------- - -OPAL_MSG_EPOW -------------- - -Used by OPAL to issue environmental and power warnings to host OS for -conditions requiring an earlier poweroff. A few examples of these are high -ambient temperature or system running on UPS power with low UPS battery. -Host OS can query OPAL via GET_EPOW_STATUS API to obtain information about -EPOW conditions present. Refer include/opal-api.h for description of -all supported EPOW events. OPAL_SYSPOWER_CHNG, OPAL_SYSPOWER_FAIL and -OPAL_SYSPOWER_INC events don't require system poweroff. - -Host OS should look for 'ibm,opal-v3-epow' string as compatible property -for 'epow' node under OPAL device-tree to determine epow support. - -OPAL_MSG_SHUTDOWN ------------------ - -Used by OPAL to inform the host OS it must imitate a graceful shutdown. Uses -the first parameter to indicate weather the system is going down for shutdown -or a reboot. - -params[0] = 0x01 reboot, 0x00 shutdown - -OPAL_MSG_HMI_EVT ----------------- - -Used by OPAL to sends the OPAL HMI Event to the host OS that reports a -summary of HMI error and whether it was successfully recovered or not. - -HMI is a Hypervisor Maintenance Interrupt usually reports error related -to processor recovery/checkstop, NX checkstop and Timer facility. Hypervisor -then takes this opportunity to analyze and recover from some of these errors. -Hypervisor takes assistance from OPAL layer to handle and recover from -HMI. After handling HMI, OPAL layer sends the summary of error report and -status of recovery action using HMI event structure shown below. - -The HMI event structure uses version numbering to allow future enhancement -to accommodate additional members. The version start from V1 onward. -Version 0 is invalid version and unsupported. - -The current version of HMI event structure V2 and is backward compatible -to V1 version. - -Notes: -- When adding new structure to the union in future, the version number - must be bumped. -- All future versions must be backward compatible to all its older versions. -- Size of this structure should not exceed that of struct opal_msg. - -struct OpalHMIEvent { - uint8_t version; /* 0x00 */ - uint8_t severity; /* 0x01 */ - uint8_t type; /* 0x02 */ - uint8_t disposition; /* 0x03 */ - uint8_t reserved_1[4]; /* 0x04 */ - - __be64 hmer; - /* TFMR register. Valid only for TFAC and TFMR_PARITY error type. */ - __be64 tfmr; - - /* version 2 and later */ - union { - /* - * checkstop info (Core/NX). - * Valid for OpalHMI_ERROR_MALFUNC_ALERT. - */ - struct { - uint8_t xstop_type; /* enum OpalHMI_XstopType */ - uint8_t reserved_1[3]; - __be32 xstop_reason; - union { - __be32 pir; /* for CHECKSTOP_TYPE_CORE */ - __be32 chip_id; /* for CHECKSTOP_TYPE_NX */ - } u; - } xstop_error; - } u; -}; - - -OPAL_MSG_DPO ------------- - -Delayed poweroff where OPAL informs host OS that a poweroff has been -requested and a forced shutdown will happen in future. Host OS can use -OPAL_GET_DPO_STATUS API to query OPAL the number of seconds remaining -before a forced poweroff will occur. - -OPAL_MSG_PRD ------------- - -This message is a OPAL-to-HBRT notification, and contains a -struct opal_prd_msg: - - enum opal_prd_msg_type { - OPAL_PRD_MSG_TYPE_INIT = 0, /* HBRT --> OPAL */ - OPAL_PRD_MSG_TYPE_FINI, /* HBRT --> OPAL */ - OPAL_PRD_MSG_TYPE_ATTN, /* HBRT <-- OPAL */ - OPAL_PRD_MSG_TYPE_ATTN_ACK, /* HBRT --> OPAL */ - OPAL_PRD_MSG_TYPE_OCC_ERROR, /* HBRT <-- OPAL */ - OPAL_PRD_MSG_TYPE_OCC_RESET, /* HBRT <-- OPAL */ - }; - - struct opal_prd_msg { - uint8_t type; - uint8_t pad[3]; - __be32 token; - union { - struct { - __be64 version; - __be64 ipoll; - } init; - struct { - __be64 proc; - __be64 ipoll_status; - __be64 ipoll_mask; - } attn; - struct { - __be64 proc; - __be64 ipoll_ack; - } attn_ack; - struct { - __be64 chip; - } occ_error; - struct { - __be64 chip; - } occ_reset; - }; - }; - -Responses from the kernel use the same message format, but are passed -through the opal_prd_msg call. - -OPAL_MSG_OCC ------------- - -This is used by OPAL to inform host about OCC events like OCC reset, -OCC load and throttle status change by OCC which can indicate the -host the reason for frequency throttling/unthrottling. - -#define OCC_RESET 0 -#define OCC_LOAD 1 -#define OCC_THROTTLE 2 -#define OCC_MAX_THROTTLE_STATUS 5 -/* - * struct opal_occ_msg: - * type: OCC_RESET, OCC_LOAD, OCC_THROTTLE - * chip: chip id - * throttle status: Indicates the reason why OCC may have limited - * the max Pstate of the chip. - * 0x00 = No throttle - * 0x01 = Power Cap - * 0x02 = Processor Over Temperature - * 0x03 = Power Supply Failure (currently not used) - * 0x04 = Over current (currently not used) - * 0x05 = OCC Reset (not reliable as some failures will not allow for - * OCC to update throttle status) - */ -struct opal_occ_msg { - __be64 type; - __be64 chip; - __be64 throttle_status; -}; - -Host should read opal_occ_msg.chip and opal_occ_msg.throttle_status -only when opal_occ_msg.type = OCC_THROTTLE. -If host receives OCC_THROTTLE after an OCC_RESET then this throttle -message will have a special meaning which indicates that all the OCCs -have become active after a reset. In such cases opal_occ_msg.chip and -opal_occ_msg.throttle_status will be set to 0 and host should not use -these values. - -If opal_occ_msg.type > 2 then host should ignore the message for now, -new events can be defined for opal_occ_msg.type in the future versions -of OPAL. diff --git a/doc/opal-api/opal-pci-get-phb-diag-data2-64.rst b/doc/opal-api/opal-pci-get-phb-diag-data2-64.rst new file mode 100644 index 0000000..837cbb9 --- /dev/null +++ b/doc/opal-api/opal-pci-get-phb-diag-data2-64.rst @@ -0,0 +1,24 @@ +OPAL_PCI_GET_PHB_DIAG_DATA2 +--------------------------- +Get PCI diagnostic data from a given PHB + +Parameters: + uint64_t phb_id: the ID of the PHB you want to retrieve data from + void *diag_buffer: an allocated buffer to store diag data in + uint64_t diag_buffer_len: size in bytes of the diag buffer + +Calling: + +Retrieve the PHB's diagnostic data. The diagnostic data is stored in the +buffer pointed by @diag_buffer. Different PHB versions will store different +diagnostics, defined in include/opal-api.h as "struct OpalIoErrorData". + +OPAL_PCI_GET_PHB_DIAG_DATA is deprecated and OPAL_PCI_GET_PHB_DIAG_DATA2 should +be used instead. + +Return Codes: + +OPAL_SUCCESS - Diagnostic data has been retrieved and stored successfully +OPAL_PARAMETER - The given buffer is too small to store the diagnostic data +OPAL_HARDWARE - The PHB is in a broken state and its data cannot be retreived +OPAL_UNSUPPORTED - Diagnostic data is not implemented for this PHB type diff --git a/doc/opal-api/opal-pci-get-phb-diag-data2-64.txt b/doc/opal-api/opal-pci-get-phb-diag-data2-64.txt deleted file mode 100644 index 837cbb9..0000000 --- a/doc/opal-api/opal-pci-get-phb-diag-data2-64.txt +++ /dev/null @@ -1,24 +0,0 @@ -OPAL_PCI_GET_PHB_DIAG_DATA2 ---------------------------- -Get PCI diagnostic data from a given PHB - -Parameters: - uint64_t phb_id: the ID of the PHB you want to retrieve data from - void *diag_buffer: an allocated buffer to store diag data in - uint64_t diag_buffer_len: size in bytes of the diag buffer - -Calling: - -Retrieve the PHB's diagnostic data. The diagnostic data is stored in the -buffer pointed by @diag_buffer. Different PHB versions will store different -diagnostics, defined in include/opal-api.h as "struct OpalIoErrorData". - -OPAL_PCI_GET_PHB_DIAG_DATA is deprecated and OPAL_PCI_GET_PHB_DIAG_DATA2 should -be used instead. - -Return Codes: - -OPAL_SUCCESS - Diagnostic data has been retrieved and stored successfully -OPAL_PARAMETER - The given buffer is too small to store the diagnostic data -OPAL_HARDWARE - The PHB is in a broken state and its data cannot be retreived -OPAL_UNSUPPORTED - Diagnostic data is not implemented for this PHB type diff --git a/doc/opal-api/opal-pci-get-power-state-120.rst b/doc/opal-api/opal-pci-get-power-state-120.rst new file mode 100644 index 0000000..420cf8d --- /dev/null +++ b/doc/opal-api/opal-pci-get-power-state-120.rst @@ -0,0 +1,19 @@ +OPAL_PCI_GET_POWER_STATE +--------------------------- + +Get PCI slot power state + +Parameters: + uint64_t id: PCI slot ID + uint64_t data: memory buffer pointer for power state + +Calling: + +Retrieve PCI slot's power state. The retrieved power state is stored +in buffer pointed by @data. + +Return Codes: + +OPAL_SUCCESS - PCI slot's power state is retrieved successfully +OPAL_PARAMETER - The indicated PCI slot isn't found +OPAL_UNSUPPORTED - Power state retrieval not supported on the PCI slot diff --git a/doc/opal-api/opal-pci-get-power-state-120.txt b/doc/opal-api/opal-pci-get-power-state-120.txt deleted file mode 100644 index 420cf8d..0000000 --- a/doc/opal-api/opal-pci-get-power-state-120.txt +++ /dev/null @@ -1,19 +0,0 @@ -OPAL_PCI_GET_POWER_STATE ---------------------------- - -Get PCI slot power state - -Parameters: - uint64_t id: PCI slot ID - uint64_t data: memory buffer pointer for power state - -Calling: - -Retrieve PCI slot's power state. The retrieved power state is stored -in buffer pointed by @data. - -Return Codes: - -OPAL_SUCCESS - PCI slot's power state is retrieved successfully -OPAL_PARAMETER - The indicated PCI slot isn't found -OPAL_UNSUPPORTED - Power state retrieval not supported on the PCI slot diff --git a/doc/opal-api/opal-pci-get-presence-state-119.rst b/doc/opal-api/opal-pci-get-presence-state-119.rst new file mode 100644 index 0000000..f3fbd83 --- /dev/null +++ b/doc/opal-api/opal-pci-get-presence-state-119.rst @@ -0,0 +1,22 @@ +OPAL_PCI_GET_PRESENCE_STATE +--------------------------- + +Get PCI slot presence state + +Parameters: + uint64_t id: PCI slot ID + uint64_t data: memory buffer pointer for presence state + +Calling: + +Retrieve PCI slot's presence state. The detected presence means there are +adapters inserted to the PCI slot. Otherwise, the PCI slot is regarded as +an empty one. The typical use is to ensure there are adapters existing +before probing the PCI slot in PCI hot add path. The retrieved presence +state is stored in buffer pointed by @data. + +Return Codes: + +OPAL_SUCCESS - PCI slot's presence state is retrieved successfully +OPAL_PARAMETER - The indicated PCI slot isn't found +OPAL_UNSUPPORTED - Presence retrieval not supported on the PCI slot diff --git a/doc/opal-api/opal-pci-get-presence-state-119.txt b/doc/opal-api/opal-pci-get-presence-state-119.txt deleted file mode 100644 index f3fbd83..0000000 --- a/doc/opal-api/opal-pci-get-presence-state-119.txt +++ /dev/null @@ -1,22 +0,0 @@ -OPAL_PCI_GET_PRESENCE_STATE ---------------------------- - -Get PCI slot presence state - -Parameters: - uint64_t id: PCI slot ID - uint64_t data: memory buffer pointer for presence state - -Calling: - -Retrieve PCI slot's presence state. The detected presence means there are -adapters inserted to the PCI slot. Otherwise, the PCI slot is regarded as -an empty one. The typical use is to ensure there are adapters existing -before probing the PCI slot in PCI hot add path. The retrieved presence -state is stored in buffer pointed by @data. - -Return Codes: - -OPAL_SUCCESS - PCI slot's presence state is retrieved successfully -OPAL_PARAMETER - The indicated PCI slot isn't found -OPAL_UNSUPPORTED - Presence retrieval not supported on the PCI slot diff --git a/doc/opal-api/opal-pci-get-set-xive-reissue-35-36.rst b/doc/opal-api/opal-pci-get-set-xive-reissue-35-36.rst new file mode 100644 index 0000000..897bc37 --- /dev/null +++ b/doc/opal-api/opal-pci-get-set-xive-reissue-35-36.rst @@ -0,0 +1,17 @@ +OPAL_PCI_GET_XIVE_REISSUE and OPAL_PCI_SET_XIVE_REISSUE +------------------------------------------------------- + +static int64_t opal_pci_get_xive_reissue(uint64_t phb_id __unused, + uint32_t xive_number __unused, + uint8_t *p_bit __unused, + uint8_t *q_bit __unused) + +static int64_t opal_pci_set_xive_reissue(uint64_t phb_id __unused, + uint32_t xive_number __unused, + uint8_t p_bit __unused, + uint8_t q_bit __unused) + + +Both of these calls are remnants from previous OPAL versions, calling either +of them shall return OPAL_UNSUPPORTED. + diff --git a/doc/opal-api/opal-pci-get-set-xive-reissue-35-36.txt b/doc/opal-api/opal-pci-get-set-xive-reissue-35-36.txt deleted file mode 100644 index 897bc37..0000000 --- a/doc/opal-api/opal-pci-get-set-xive-reissue-35-36.txt +++ /dev/null @@ -1,17 +0,0 @@ -OPAL_PCI_GET_XIVE_REISSUE and OPAL_PCI_SET_XIVE_REISSUE -------------------------------------------------------- - -static int64_t opal_pci_get_xive_reissue(uint64_t phb_id __unused, - uint32_t xive_number __unused, - uint8_t *p_bit __unused, - uint8_t *q_bit __unused) - -static int64_t opal_pci_set_xive_reissue(uint64_t phb_id __unused, - uint32_t xive_number __unused, - uint8_t p_bit __unused, - uint8_t q_bit __unused) - - -Both of these calls are remnants from previous OPAL versions, calling either -of them shall return OPAL_UNSUPPORTED. - diff --git a/doc/opal-api/opal-pci-map-pe-dma-window-44.rst b/doc/opal-api/opal-pci-map-pe-dma-window-44.rst new file mode 100644 index 0000000..0793209 --- /dev/null +++ b/doc/opal-api/opal-pci-map-pe-dma-window-44.rst @@ -0,0 +1,92 @@ +OPAL_PCI_MAP_PE_DMA_WINDOW +-------------------------- + +#define OPAL_PCI_MAP_PE_DMA_WINDOW 44 + + +static int64_t opal_pci_map_pe_dma_window(uint64_t phb_id, uint16_t pe_number, + uint16_t window_id, + uint16_t tce_levels, + uint64_t tce_table_addr, + uint64_t tce_table_size, + uint64_t tce_page_size) + +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 create a DMA window and map it to a PE. This +call returns the address in PCI memory that corresponds to the specified DMA +window, which in part may depend on the particular PHB DMA window used. An +address that is all zeros in the upper 32 bits reflects a DMA window enabled +for 32-bit DMA addresses. + +The overall size of the DMA window in PCI memory is determined by the number +of tce_levels times the tce_table_size times the tce_page_size. + + phb_id is the value from the PHB node ibm,opal-phbid property. + + dma_window_number specifies the DMA window + +For ibm,opal-ioda PHBs the dma_window_number is an index from 0 to the PHB +total number of windows minus 1. For ibm,opal-ioda2 PHBs the DMA window_number +is an index from 0 to n-1, where n is the number of windows per window set, +within the window set associated with the specified PE number. + + pe_number is the index of the PE that is authorized to DMA to this window + address space in PCI memory, + + tce_levels is the number of TCE table levels in the translation hiearchy, + from 1 to ibm,opal-dmawins property . + + tce_table_addr is the 64-bit system real address of the first level (root, + for mult-level) TCE table in the translation hiearchy. + + tce_table_size is the size, in bytes, of each TCE table in the translation + hierarchy. A value of '0' indicates to disable this DMA window. + +For ibm,opal-ioda, this must be a value in the range from +128MB / tce_page_size to 256TB / tce_page_size, and must be in the format and +matching a value in the tce_table ranges property that is minimally 256KB for +4K pages. + +A particular PE may be mapped to multiple DMA windows, each spanning a DMA +window size corresponding to the win_size32 or win_size_64 specified in the +ibm,opal-dmawins<> property. However, the TCE table base address must be +unique for each window unless it is intended that the same page address in +each DMA window is mapped through the same TCE table entry. Generally, when +mapping the same PE to multiple DMA windows, so as to create a larger overall +DMA window, it is recommended to use consecutive DMA windows and each DMA +window should use a TCE table address that is offset by the win_size value of +predecessor DMA window. + + tce_page_size is the size of PCI memory pages mapped to system real pages + through all TCE tables in the translation hierarchy. This must be the + same format as and match a value from the ibm,opal-dmawins property + . This page size applies to all TCE tables in the + translation hierarchy. + + pci_start_addr returns the starting address in PCI memory that corresponds + to this DMA window based on the input translation parameter values. + + pci_mem_type selects whether this DMA window should be created in 32-bit + or 64-bit PCI memory. The input values correspond to the same PCI memory + space locators as MMIO spaces in the ranges<> property -- 0x2 indicated + 32-bit PCI memory and 0x3 indicates 64-bit memory. + +Window 0 for both ibm,opal-ioda and ibm,opal-ioda2 PHBs must be within 32-bit +PCI memory and this call return opal_parameter for calls that specify window +0 in 64-bit PCI memory. + +The DMA win_size property for 32 bit DMA windows limits the number of +ibm,opal-ioda PHB windows that can map32-bit address space. For example, with +a win_size_32 = 256MB, only 16 DMA windows (and therefore no more than 16 +distinct PEs) can map the 4GB of 32-bit PCI memory for DMA. OPAL does not +police this limitation. + +Return value: + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->map_pe_dma_window) + return OPAL_UNSUPPORTED; + diff --git a/doc/opal-api/opal-pci-map-pe-dma-window-44.txt b/doc/opal-api/opal-pci-map-pe-dma-window-44.txt deleted file mode 100644 index 0793209..0000000 --- a/doc/opal-api/opal-pci-map-pe-dma-window-44.txt +++ /dev/null @@ -1,92 +0,0 @@ -OPAL_PCI_MAP_PE_DMA_WINDOW --------------------------- - -#define OPAL_PCI_MAP_PE_DMA_WINDOW 44 - - -static int64_t opal_pci_map_pe_dma_window(uint64_t phb_id, uint16_t pe_number, - uint16_t window_id, - uint16_t tce_levels, - uint64_t tce_table_addr, - uint64_t tce_table_size, - uint64_t tce_page_size) - -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 create a DMA window and map it to a PE. This -call returns the address in PCI memory that corresponds to the specified DMA -window, which in part may depend on the particular PHB DMA window used. An -address that is all zeros in the upper 32 bits reflects a DMA window enabled -for 32-bit DMA addresses. - -The overall size of the DMA window in PCI memory is determined by the number -of tce_levels times the tce_table_size times the tce_page_size. - - phb_id is the value from the PHB node ibm,opal-phbid property. - - dma_window_number specifies the DMA window - -For ibm,opal-ioda PHBs the dma_window_number is an index from 0 to the PHB -total number of windows minus 1. For ibm,opal-ioda2 PHBs the DMA window_number -is an index from 0 to n-1, where n is the number of windows per window set, -within the window set associated with the specified PE number. - - pe_number is the index of the PE that is authorized to DMA to this window - address space in PCI memory, - - tce_levels is the number of TCE table levels in the translation hiearchy, - from 1 to ibm,opal-dmawins property . - - tce_table_addr is the 64-bit system real address of the first level (root, - for mult-level) TCE table in the translation hiearchy. - - tce_table_size is the size, in bytes, of each TCE table in the translation - hierarchy. A value of '0' indicates to disable this DMA window. - -For ibm,opal-ioda, this must be a value in the range from -128MB / tce_page_size to 256TB / tce_page_size, and must be in the format and -matching a value in the tce_table ranges property that is minimally 256KB for -4K pages. - -A particular PE may be mapped to multiple DMA windows, each spanning a DMA -window size corresponding to the win_size32 or win_size_64 specified in the -ibm,opal-dmawins<> property. However, the TCE table base address must be -unique for each window unless it is intended that the same page address in -each DMA window is mapped through the same TCE table entry. Generally, when -mapping the same PE to multiple DMA windows, so as to create a larger overall -DMA window, it is recommended to use consecutive DMA windows and each DMA -window should use a TCE table address that is offset by the win_size value of -predecessor DMA window. - - tce_page_size is the size of PCI memory pages mapped to system real pages - through all TCE tables in the translation hierarchy. This must be the - same format as and match a value from the ibm,opal-dmawins property - . This page size applies to all TCE tables in the - translation hierarchy. - - pci_start_addr returns the starting address in PCI memory that corresponds - to this DMA window based on the input translation parameter values. - - pci_mem_type selects whether this DMA window should be created in 32-bit - or 64-bit PCI memory. The input values correspond to the same PCI memory - space locators as MMIO spaces in the ranges<> property -- 0x2 indicated - 32-bit PCI memory and 0x3 indicates 64-bit memory. - -Window 0 for both ibm,opal-ioda and ibm,opal-ioda2 PHBs must be within 32-bit -PCI memory and this call return opal_parameter for calls that specify window -0 in 64-bit PCI memory. - -The DMA win_size property for 32 bit DMA windows limits the number of -ibm,opal-ioda PHB windows that can map32-bit address space. For example, with -a win_size_32 = 256MB, only 16 DMA windows (and therefore no more than 16 -distinct PEs) can map the 4GB of 32-bit PCI memory for DMA. OPAL does not -police this limitation. - -Return value: - if (!phb) - return OPAL_PARAMETER; - if (!phb->ops->map_pe_dma_window) - return OPAL_UNSUPPORTED; - diff --git a/doc/opal-api/opal-pci-map-pe-dma-window-real-45.rst b/doc/opal-api/opal-pci-map-pe-dma-window-real-45.rst new file mode 100644 index 0000000..28ea112 --- /dev/null +++ b/doc/opal-api/opal-pci-map-pe-dma-window-real-45.rst @@ -0,0 +1,39 @@ +OPAL_PCI_MAP_PE_DMA_WINDOW_REAL +------------------------------- + +#define OPAL_PCI_MAP_PE_DMA_WINDOW_REAL 45 + +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 initialize the specified DMA window for +untranslated DMA addresses. This allows a PE to DMA directly to system memory +without TCE translation. The DMA window PCI memory address is equal to the +system memory real address. The PHB passes PCI address bits 04:63 directly to +system real address bits 04:63 when PCI address bits 04:39 are within the +region specified by mem_addr t0 mem_addr + window_size. + +The addresses must be 16MB aligned and a multiple of 16MB in size. + + phb_id is the value from the PHB node ibm,opal-phbid property. + + dma_window_number specifies the DMA window + +For ibm,opal-ioda PHBs the dma_window_number is an index from 0 to the PHB +total number of windows minus 1. For ibm,opal-ioda2 PHBs the DMA window_number +is an index from 0 to n-1, where n is the number of windows per window set, +within the window set associated with the specified PE number. + + pe_number is the index of the PE that is authorized to DMA to this window + address space in PCI memory, + + mem_addr is the starting 64-bit system real address mapped directly to the + starting address in PCI memory. Addresses below 4GB are zero in bits above + bit 32. This value must be aligned on a 16MB boundary; OPAL returns + OPAL_PARAMETER for any value that is not a multiple of 16MB. + + window_size is the size, in bytes, of the address range defined by this + window. This value must be a multiple of 16MB; OPAL returns OPAL_PARAMETER + for any value that is not a multiple of 16MB. A value of '0' indicates to + disable this DMA window. diff --git a/doc/opal-api/opal-pci-map-pe-dma-window-real-45.txt b/doc/opal-api/opal-pci-map-pe-dma-window-real-45.txt deleted file mode 100644 index 28ea112..0000000 --- a/doc/opal-api/opal-pci-map-pe-dma-window-real-45.txt +++ /dev/null @@ -1,39 +0,0 @@ -OPAL_PCI_MAP_PE_DMA_WINDOW_REAL -------------------------------- - -#define OPAL_PCI_MAP_PE_DMA_WINDOW_REAL 45 - -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 initialize the specified DMA window for -untranslated DMA addresses. This allows a PE to DMA directly to system memory -without TCE translation. The DMA window PCI memory address is equal to the -system memory real address. The PHB passes PCI address bits 04:63 directly to -system real address bits 04:63 when PCI address bits 04:39 are within the -region specified by mem_addr t0 mem_addr + window_size. - -The addresses must be 16MB aligned and a multiple of 16MB in size. - - phb_id is the value from the PHB node ibm,opal-phbid property. - - dma_window_number specifies the DMA window - -For ibm,opal-ioda PHBs the dma_window_number is an index from 0 to the PHB -total number of windows minus 1. For ibm,opal-ioda2 PHBs the DMA window_number -is an index from 0 to n-1, where n is the number of windows per window set, -within the window set associated with the specified PE number. - - pe_number is the index of the PE that is authorized to DMA to this window - address space in PCI memory, - - mem_addr is the starting 64-bit system real address mapped directly to the - starting address in PCI memory. Addresses below 4GB are zero in bits above - bit 32. This value must be aligned on a 16MB boundary; OPAL returns - OPAL_PARAMETER for any value that is not a multiple of 16MB. - - window_size is the size, in bytes, of the address range defined by this - window. This value must be a multiple of 16MB; OPAL returns OPAL_PARAMETER - for any value that is not a multiple of 16MB. A value of '0' indicates to - disable this DMA window. diff --git a/doc/opal-api/opal-pci-map-pe-mmio-window-29.rst b/doc/opal-api/opal-pci-map-pe-mmio-window-29.rst new file mode 100644 index 0000000..4f43506 --- /dev/null +++ b/doc/opal-api/opal-pci-map-pe-mmio-window-29.rst @@ -0,0 +1,39 @@ +OPAL_PCI_MAP_PE_MMIO_WINDOW +--------------------------- +#define OPAL_PCI_MAP_PE_MMIO_WINDOW 29 + +static int64_t opal_pci_map_pe_mmio_window(uint64_t phb_id, uint16_t pe_number, + uint16_t window_type, + uint16_t window_num, + uint16_t segment_num) + +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 map a segment of MMIO address space to a PE. + + phb_id is the value from the PHB node ibm,opal-phbid property. + + window_type specifies 32-bit or 64-bit PCI memory + + '0' selects PCI IO Space. ibm,opal-ioda2 PHBs do not support IO space, + and OPAL returns opal_unsupported if called for IO windows. + + '1' selects 32-bit PCI memory space + + '2' selects 64 bit PCI memory space + + window_num is the MMIO window number within the specified PCI memory space + + segment_num is an index from 0 to the number of segments minus 1 defined + or this window, and selects a particular segment within the specified + window. + + +Return value: + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->map_pe_mmio_window) + return OPAL_UNSUPPORTED; + diff --git a/doc/opal-api/opal-pci-map-pe-mmio-window-29.txt b/doc/opal-api/opal-pci-map-pe-mmio-window-29.txt deleted file mode 100644 index 4f43506..0000000 --- a/doc/opal-api/opal-pci-map-pe-mmio-window-29.txt +++ /dev/null @@ -1,39 +0,0 @@ -OPAL_PCI_MAP_PE_MMIO_WINDOW ---------------------------- -#define OPAL_PCI_MAP_PE_MMIO_WINDOW 29 - -static int64_t opal_pci_map_pe_mmio_window(uint64_t phb_id, uint16_t pe_number, - uint16_t window_type, - uint16_t window_num, - uint16_t segment_num) - -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 map a segment of MMIO address space to a PE. - - phb_id is the value from the PHB node ibm,opal-phbid property. - - window_type specifies 32-bit or 64-bit PCI memory - - '0' selects PCI IO Space. ibm,opal-ioda2 PHBs do not support IO space, - and OPAL returns opal_unsupported if called for IO windows. - - '1' selects 32-bit PCI memory space - - '2' selects 64 bit PCI memory space - - window_num is the MMIO window number within the specified PCI memory space - - segment_num is an index from 0 to the number of segments minus 1 defined - or this window, and selects a particular segment within the specified - window. - - -Return value: - if (!phb) - return OPAL_PARAMETER; - if (!phb->ops->map_pe_mmio_window) - return OPAL_UNSUPPORTED; - diff --git a/doc/opal-api/opal-pci-phb-mmio-enable-27.rst b/doc/opal-api/opal-pci-phb-mmio-enable-27.rst new file mode 100644 index 0000000..9bff057 --- /dev/null +++ b/doc/opal-api/opal-pci-phb-mmio-enable-27.rst @@ -0,0 +1,44 @@ +OPAL_PCI_PHB_MMIO_ENABLE +------------------------ + +#define OPAL_PCI_PHB_MMIO_ENABLE 27 + +static int64_t opal_pci_phb_mmio_enable(uint64_t phb_id, uint16_t window_type, + uint16_t window_num, uint16_t enable) + +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 enable or disable PHB decode of the PCI IO +and Memory address spaces below that PHB. Window_num selects an mmio window +within that address space. Enable set to '1' enables the PHB to decode and +forward system real addresses to PCI memory, while enable set to '0' disables +PHB decode and forwarding for the address range defined in a particular MMIO +window. + +Not all PHB hardware may support disabling some or all MMIO windows. OPAL +returns OPAL_UNSUPPORTED if called to disable an MMIO window for which +hardware does not support disable. KVM may call this function for all MMIO +windows and ignore the opal_unsuppsorted return code so long as KVM has +disabled MMIO to all downstream PCI devices and assured that KVM and OS guest +partitions cannot issue CI loads/stores to these address spaces from the +processor (e.g.,via HPT). + +OPAL returns OPAL_SUCCESS for calls to OPAL to enable them for PHBs that do +not support disable. + + phb_id is the value from the PHB node ibm,opal-phbid property. + + window_type specifies 32-bit or 64-bit PCI memory + + '0' selects PCI IO Space + + '1' selects 32-bit PCI memory space + + '2' selects 64 bit PCI memory space + + window_num is the MMIO window number within the specified PCI memory space + + enable specifies to enable or disable this MMIO window. diff --git a/doc/opal-api/opal-pci-phb-mmio-enable-27.txt b/doc/opal-api/opal-pci-phb-mmio-enable-27.txt deleted file mode 100644 index 9bff057..0000000 --- a/doc/opal-api/opal-pci-phb-mmio-enable-27.txt +++ /dev/null @@ -1,44 +0,0 @@ -OPAL_PCI_PHB_MMIO_ENABLE ------------------------- - -#define OPAL_PCI_PHB_MMIO_ENABLE 27 - -static int64_t opal_pci_phb_mmio_enable(uint64_t phb_id, uint16_t window_type, - uint16_t window_num, uint16_t enable) - -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 enable or disable PHB decode of the PCI IO -and Memory address spaces below that PHB. Window_num selects an mmio window -within that address space. Enable set to '1' enables the PHB to decode and -forward system real addresses to PCI memory, while enable set to '0' disables -PHB decode and forwarding for the address range defined in a particular MMIO -window. - -Not all PHB hardware may support disabling some or all MMIO windows. OPAL -returns OPAL_UNSUPPORTED if called to disable an MMIO window for which -hardware does not support disable. KVM may call this function for all MMIO -windows and ignore the opal_unsuppsorted return code so long as KVM has -disabled MMIO to all downstream PCI devices and assured that KVM and OS guest -partitions cannot issue CI loads/stores to these address spaces from the -processor (e.g.,via HPT). - -OPAL returns OPAL_SUCCESS for calls to OPAL to enable them for PHBs that do -not support disable. - - phb_id is the value from the PHB node ibm,opal-phbid property. - - window_type specifies 32-bit or 64-bit PCI memory - - '0' selects PCI IO Space - - '1' selects 32-bit PCI memory space - - '2' selects 64 bit PCI memory space - - window_num is the MMIO window number within the specified PCI memory space - - enable specifies to enable or disable this MMIO window. diff --git a/doc/opal-api/opal-pci-set-mve-33.rst b/doc/opal-api/opal-pci-set-mve-33.rst new file mode 100644 index 0000000..f407d41 --- /dev/null +++ b/doc/opal-api/opal-pci-set-mve-33.rst @@ -0,0 +1,36 @@ +OPAL_PCI_SET_MVE +---------------- + +#define OPAL_PCI_SET_MVE 33 + +static int64_t opal_pci_set_mve(uint64_t phb_id, uint32_t mve_number, + uint32_t pe_number) + +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 bind a PE to an MSI Validation Table Entry +(MVE) in the PHB. The MVE compares the MSI requester (RID) to a PE RID, +including within the XIVE, to validate that the requester is authorized to +signal an interrupt to the associated DMA address for a message value that +selects a particular XIVE. + + The phb_id parameter is the value from the PHB node ibm,opal-phbid + property. + + The mve_number is the index, from 0 to ibm,opal,ibm-num-msi-ports minus1 + + the pe_number is the index of a PE, from 0 to ibm,opal-num-pes minus 1. + + This call maps an MVE to a PE and PE RID domain. OPAL uses the PELT to + determine the PE domain. OPAL treats this call as a NOP for IODA2 PHBs + and returns a status of OPAL_SUCCESS. + + +Return value: + + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->set_mve) + return OPAL_UNSUPPORTED; diff --git a/doc/opal-api/opal-pci-set-mve-33.txt b/doc/opal-api/opal-pci-set-mve-33.txt deleted file mode 100644 index f407d41..0000000 --- a/doc/opal-api/opal-pci-set-mve-33.txt +++ /dev/null @@ -1,36 +0,0 @@ -OPAL_PCI_SET_MVE ----------------- - -#define OPAL_PCI_SET_MVE 33 - -static int64_t opal_pci_set_mve(uint64_t phb_id, uint32_t mve_number, - uint32_t pe_number) - -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 bind a PE to an MSI Validation Table Entry -(MVE) in the PHB. The MVE compares the MSI requester (RID) to a PE RID, -including within the XIVE, to validate that the requester is authorized to -signal an interrupt to the associated DMA address for a message value that -selects a particular XIVE. - - The phb_id parameter is the value from the PHB node ibm,opal-phbid - property. - - The mve_number is the index, from 0 to ibm,opal,ibm-num-msi-ports minus1 - - the pe_number is the index of a PE, from 0 to ibm,opal-num-pes minus 1. - - This call maps an MVE to a PE and PE RID domain. OPAL uses the PELT to - determine the PE domain. OPAL treats this call as a NOP for IODA2 PHBs - and returns a status of OPAL_SUCCESS. - - -Return value: - - if (!phb) - return OPAL_PARAMETER; - if (!phb->ops->set_mve) - return OPAL_UNSUPPORTED; diff --git a/doc/opal-api/opal-pci-set-mve-enable-34.rst b/doc/opal-api/opal-pci-set-mve-enable-34.rst new file mode 100644 index 0000000..4c13d3c --- /dev/null +++ b/doc/opal-api/opal-pci-set-mve-enable-34.rst @@ -0,0 +1,35 @@ +OPAL_PCI_SET_MVE_ENABLE +----------------------- + +#define OPAL_PCI_SET_MVE_ENABLE 34 + +static int64_t opal_pci_set_mve_enable(uint64_t phb_id, uint32_t mve_number, + uint32_t state) + +enum OpalMveEnableAction { + OPAL_DISABLE_MVE = 0, + OPAL_ENABLE_MVE = 1 +}; + +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 enable or disable an MVE to respond to an MSI +DMA address and message data value. + +The phb_id parameter is the value from the PHB node ibm,opal-phbid + property. + +The mve_number is the index, from 0 to ibm,opal,ibm-num-msi-ports minus1 + +A '1' value of the state parameter indicates to enable the MVE and a '0' +value indicates to disable the MVE. + +This call sets the MVE to an enabled (1) or disabled (0) state. + +Return value: + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->set_mve_enable) + return OPAL_UNSUPPORTED; diff --git a/doc/opal-api/opal-pci-set-mve-enable-34.txt b/doc/opal-api/opal-pci-set-mve-enable-34.txt deleted file mode 100644 index 4c13d3c..0000000 --- a/doc/opal-api/opal-pci-set-mve-enable-34.txt +++ /dev/null @@ -1,35 +0,0 @@ -OPAL_PCI_SET_MVE_ENABLE ------------------------ - -#define OPAL_PCI_SET_MVE_ENABLE 34 - -static int64_t opal_pci_set_mve_enable(uint64_t phb_id, uint32_t mve_number, - uint32_t state) - -enum OpalMveEnableAction { - OPAL_DISABLE_MVE = 0, - OPAL_ENABLE_MVE = 1 -}; - -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 enable or disable an MVE to respond to an MSI -DMA address and message data value. - -The phb_id parameter is the value from the PHB node ibm,opal-phbid - property. - -The mve_number is the index, from 0 to ibm,opal,ibm-num-msi-ports minus1 - -A '1' value of the state parameter indicates to enable the MVE and a '0' -value indicates to disable the MVE. - -This call sets the MVE to an enabled (1) or disabled (0) state. - -Return value: - if (!phb) - return OPAL_PARAMETER; - if (!phb->ops->set_mve_enable) - return OPAL_UNSUPPORTED; diff --git a/doc/opal-api/opal-pci-set-pe-31.rst b/doc/opal-api/opal-pci-set-pe-31.rst new file mode 100644 index 0000000..bfe3890 --- /dev/null +++ b/doc/opal-api/opal-pci-set-pe-31.rst @@ -0,0 +1,74 @@ +OPAL_PCI_SET_PE +--------------- + +#define OPAL_PCI_SET_PE 31 + +NOTE: The following two paragraphs come from some old documentation and +have not been checked for accuracy. Same goes for bus_compare, dev_compare +and func_compare documentation. Do *NOT* assume this documentation is correct +without checking the source. + +A host OS calls this function to map a PCIE function (RID), or range of +function bus/dev/funcs (RIDs), to a PHB PE. The bus, device, func, and +compare parameters define a range of bus, device, or function numbers to +define a range of RIDs within this domain. A value of "7" for the bus_compare, +and non-zero for the dev_compare and func_compare, define exactly one function +RID to be a PE (within a PE number domain). + +This must be called prior to ALL other OPAL calls that take a PE number +argument, for OPAL to correlate the RID (bus/dev/func) domain of the PE. If a +PE domain is changed, the host must call this to reset the PE bus/dev/func +domain and then call all other OPAL calls that map PHB IODA resources to +update those domains within PHB facilities. + +static int64_t opal_pci_set_pe(uint64_t phb_id, uint64_t pe_number, + uint64_t bus_dev_func, uint8_t bus_compare, + uint8_t dev_compare, uint8_t func_compare, + uint8_t pe_action) + +The phb_id parameter is the value from the PHB node ibm,opal-phbid property. + +the pe_number is the index of a PE, from 0 to ibm,opal-num-pes minus 1. + +the bus_compare parameter is a value from 0 to 7 indicating which bus number +bits define the range of buses in a PE domain: + + 0 = do not validate against RID bus number (PE = all bus numbers) + 2 = compare high order 3 bits of RID bus number to high order 3 bits of + PE bus number + 3 = compare high order 4 bits of RID bus number to high order 4 bits of + PE bus number + : + 6 = compare high order 7 bits of RID bus number to high order 7 bits of + PE bus number + 7 = compare all bits of RID bus number to all bits of PE bus number + +the dev_compare parameter indicates to compare the RID device number to the PE +device number or not. '0' signifies that the RID device number is not compared +-- essentially all device numbers within the bus and function number range of +this PE are also within this PE. Non-zero signifies to compare the RID device +number to the PE device number, such that only that device number is in the PE +domain, for all buses and function numbers in the PE domain. + +the func_compare parameter indicates to compare the RID function number to the +PE function number or not. '0' signifies that the RID function number is not +compared -- essentially all function numbers within the bus and device number +range of this PE are also within this PE. Non-zero signifies to compare the +RID function number to the PE function number, such that only that function +number is in the PE domain, for all buses and device numbers in the PE domain. + +pe_action is one of: +enum OpalPeAction { + OPAL_UNMAP_PE = 0, + OPAL_MAP_PE = 1 +}; + + +Return value: +- OPAL_PARAMETER if: + - invalid phb + - invalid pe_action + - invalid bus_dev_func + - invalid bus_compare +- if PHB does not support set_pe operation, OPAL_UNSUPPORTED +- OPAL_SUCCESS if opreation was successful diff --git a/doc/opal-api/opal-pci-set-pe-31.txt b/doc/opal-api/opal-pci-set-pe-31.txt deleted file mode 100644 index bfe3890..0000000 --- a/doc/opal-api/opal-pci-set-pe-31.txt +++ /dev/null @@ -1,74 +0,0 @@ -OPAL_PCI_SET_PE ---------------- - -#define OPAL_PCI_SET_PE 31 - -NOTE: The following two paragraphs come from some old documentation and -have not been checked for accuracy. Same goes for bus_compare, dev_compare -and func_compare documentation. Do *NOT* assume this documentation is correct -without checking the source. - -A host OS calls this function to map a PCIE function (RID), or range of -function bus/dev/funcs (RIDs), to a PHB PE. The bus, device, func, and -compare parameters define a range of bus, device, or function numbers to -define a range of RIDs within this domain. A value of "7" for the bus_compare, -and non-zero for the dev_compare and func_compare, define exactly one function -RID to be a PE (within a PE number domain). - -This must be called prior to ALL other OPAL calls that take a PE number -argument, for OPAL to correlate the RID (bus/dev/func) domain of the PE. If a -PE domain is changed, the host must call this to reset the PE bus/dev/func -domain and then call all other OPAL calls that map PHB IODA resources to -update those domains within PHB facilities. - -static int64_t opal_pci_set_pe(uint64_t phb_id, uint64_t pe_number, - uint64_t bus_dev_func, uint8_t bus_compare, - uint8_t dev_compare, uint8_t func_compare, - uint8_t pe_action) - -The phb_id parameter is the value from the PHB node ibm,opal-phbid property. - -the pe_number is the index of a PE, from 0 to ibm,opal-num-pes minus 1. - -the bus_compare parameter is a value from 0 to 7 indicating which bus number -bits define the range of buses in a PE domain: - - 0 = do not validate against RID bus number (PE = all bus numbers) - 2 = compare high order 3 bits of RID bus number to high order 3 bits of - PE bus number - 3 = compare high order 4 bits of RID bus number to high order 4 bits of - PE bus number - : - 6 = compare high order 7 bits of RID bus number to high order 7 bits of - PE bus number - 7 = compare all bits of RID bus number to all bits of PE bus number - -the dev_compare parameter indicates to compare the RID device number to the PE -device number or not. '0' signifies that the RID device number is not compared --- essentially all device numbers within the bus and function number range of -this PE are also within this PE. Non-zero signifies to compare the RID device -number to the PE device number, such that only that device number is in the PE -domain, for all buses and function numbers in the PE domain. - -the func_compare parameter indicates to compare the RID function number to the -PE function number or not. '0' signifies that the RID function number is not -compared -- essentially all function numbers within the bus and device number -range of this PE are also within this PE. Non-zero signifies to compare the -RID function number to the PE function number, such that only that function -number is in the PE domain, for all buses and device numbers in the PE domain. - -pe_action is one of: -enum OpalPeAction { - OPAL_UNMAP_PE = 0, - OPAL_MAP_PE = 1 -}; - - -Return value: -- OPAL_PARAMETER if: - - invalid phb - - invalid pe_action - - invalid bus_dev_func - - invalid bus_compare -- if PHB does not support set_pe operation, OPAL_UNSUPPORTED -- OPAL_SUCCESS if opreation was successful diff --git a/doc/opal-api/opal-pci-set-peltv-32.rst b/doc/opal-api/opal-pci-set-peltv-32.rst new file mode 100644 index 0000000..9274aab --- /dev/null +++ b/doc/opal-api/opal-pci-set-peltv-32.rst @@ -0,0 +1,52 @@ +OPAL_PCI_SET_PELTV +------------------ + +#define OPAL_PCI_SET_PELTV 32 + +WARNING: This documentation comes from an old source and is possibly not up +to date with OPALv3. Rely on this documentation only as a starting point, +use the source (and update the docs). + +static int64_t opal_pci_set_peltv(uint64_t phb_id, uint32_t parent_pe, + uint32_t child_pe, uint8_t state) + +This call sets the PELTV of a parent PE to add or remove a PE number as a PE +within that parent PE domain. The host must call this function for each child +of a parent PE. + + The phb_id parameter is the value from the PHB node ibm,opal-phbid property + + the parent_pe is the PE number of a PE that is higher in the PCI hierarchy +to other PEs, such that an error involving this parent PE should cause a +collateral PE freeze for PEs below this PE in the PCI hierarchy. For example +a switch upstream bridge is a PE that is parent to PEs reached through that +upstream bridge such that an error involving the upstream bridge +(e.g, ERR_FATAL) should cause the PHB to freeze all other PEs below that +upstream bridge (e.g., a downstream bridge, or devices below a downstream +bridge). + + the child_pe is the PE number of a PE that is lower in the PCI hierarchy +than another PE, such that an error involving that other PE should cause a +collateral PE freeze for this child PE. For example a device below a +downstream bridge of a PCIE switch is a child PE that downstream bridge PE +and the upstream bridge PE of that switch -- an ERR_Fatal from either bridge +should result in a collateral freeze of that device PE. + +enum OpalPeltvAction { + OPAL_REMOVE_PE_FROM_DOMAIN = 0, + OPAL_ADD_PE_TO_DOMAIN = 1 +}; + +OPAL Implementation Note: +WARNING TODO: CHECK IF THIS IS CORRECT FOR skiboot: +For ibm,opal-ioda2, OPAL sets the PELTV bit in all RTT entries for the parent +PE when the state argument is '1'. OPAL clears the PELTV bit in all RTT +entries for the parent PE when the state argument is '0' and setting the child +PE bit in the parent PELTV results in an all-zeros value for that PELTV. + +Return value: + + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->set_peltv) + return OPAL_UNSUPPORTED; diff --git a/doc/opal-api/opal-pci-set-peltv-32.txt b/doc/opal-api/opal-pci-set-peltv-32.txt deleted file mode 100644 index 9274aab..0000000 --- a/doc/opal-api/opal-pci-set-peltv-32.txt +++ /dev/null @@ -1,52 +0,0 @@ -OPAL_PCI_SET_PELTV ------------------- - -#define OPAL_PCI_SET_PELTV 32 - -WARNING: This documentation comes from an old source and is possibly not up -to date with OPALv3. Rely on this documentation only as a starting point, -use the source (and update the docs). - -static int64_t opal_pci_set_peltv(uint64_t phb_id, uint32_t parent_pe, - uint32_t child_pe, uint8_t state) - -This call sets the PELTV of a parent PE to add or remove a PE number as a PE -within that parent PE domain. The host must call this function for each child -of a parent PE. - - The phb_id parameter is the value from the PHB node ibm,opal-phbid property - - the parent_pe is the PE number of a PE that is higher in the PCI hierarchy -to other PEs, such that an error involving this parent PE should cause a -collateral PE freeze for PEs below this PE in the PCI hierarchy. For example -a switch upstream bridge is a PE that is parent to PEs reached through that -upstream bridge such that an error involving the upstream bridge -(e.g, ERR_FATAL) should cause the PHB to freeze all other PEs below that -upstream bridge (e.g., a downstream bridge, or devices below a downstream -bridge). - - the child_pe is the PE number of a PE that is lower in the PCI hierarchy -than another PE, such that an error involving that other PE should cause a -collateral PE freeze for this child PE. For example a device below a -downstream bridge of a PCIE switch is a child PE that downstream bridge PE -and the upstream bridge PE of that switch -- an ERR_Fatal from either bridge -should result in a collateral freeze of that device PE. - -enum OpalPeltvAction { - OPAL_REMOVE_PE_FROM_DOMAIN = 0, - OPAL_ADD_PE_TO_DOMAIN = 1 -}; - -OPAL Implementation Note: -WARNING TODO: CHECK IF THIS IS CORRECT FOR skiboot: -For ibm,opal-ioda2, OPAL sets the PELTV bit in all RTT entries for the parent -PE when the state argument is '1'. OPAL clears the PELTV bit in all RTT -entries for the parent PE when the state argument is '0' and setting the child -PE bit in the parent PELTV results in an all-zeros value for that PELTV. - -Return value: - - if (!phb) - return OPAL_PARAMETER; - if (!phb->ops->set_peltv) - return OPAL_UNSUPPORTED; diff --git a/doc/opal-api/opal-pci-set-phb-mem-window-28.rst b/doc/opal-api/opal-pci-set-phb-mem-window-28.rst new file mode 100644 index 0000000..8a355e8 --- /dev/null +++ b/doc/opal-api/opal-pci-set-phb-mem-window-28.rst @@ -0,0 +1,71 @@ +OPAL_PCI_SET_PHB_MEM_WINDOW +--------------------------- + +#define OPAL_PCI_SET_PHB_MEM_WINDOW 28 + +static int64_t opal_pci_set_phb_mem_window(uint64_t phb_id, + uint16_t window_type, + uint16_t window_num, + uint64_t addr, + uint64_t pci_addr, + uint64_t size) + +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 PHB PCI memory window parameters for +PHBs. OPAL sets IO space for P7IOC and KVM cannot relocate this. KVM should +changes these windows only while all devices below the PHB are disabled for +PCI memory ops, and with the target window in disabled state (where supported +by PHB hardware). + + phb_id is the value from the PHB node ibm,opal-phbid property. + + window_type specifies 32-bit or 64-bit PCI memory + + '0' selects IO space, and is not supported for relocation. OPAL + returns OPAL_UNSUPPORTED for this value. + + '1' selects 32-bit PCI memory space + + '2' selects 64 bit PCI memory space + + window_num is the MMIO window number within the specified PCI memory space + + starting_real_address specifies the location within sytsem (processor)real + address space this MMIO window starts. This must be a location within the + IO Hub or PHB node ibm,opal-mmio-real property. + + starting_pci_address specifies the location within PCI 32 or 64-bit + address space that this MMIO window starts. For 64-bit PCI memory, this + must be within the low order 60 bit (1 Exabyte) region of PCI memory. + Addresses above 1EB are reserved to IODA definitions. + + segment_size defines the segment size of this window, in the same format + as and a matching value from the ibm,opal-memwin32/64 + property. The window total size, in bytes, is the segment_size times the + ibm,opal-memwin32/64 property and must not extend beyond + the ibm,opal-mmio-real property range within system real address space. + The total MMIO window size is the segment_size times the num_segments + supported for the specifice window. The host must assure that the + cumulative address space for all enabled windows does not exceed the total + PHB 32-bit or 64-bit real address window space, or extend outside these + address ranges, and that no windows overlap each other in real or PCI + address space. OPAL does not validate those conditions. + +A segment size of '0' indicates to disable this MMIO window. If the PHB +hardware does not support disabling a window, OPAL returns OPAL_UNSUPPORTED +status. + +The size of the system real and PCI memory spaces are equal and defined by +segment_size times the number of segments within this MMIO window. + +The host must set PHB memory windows to be within the system real address +ranges indicated in the PHB parent HDT hub node ibm,opal-mmio-real property. + +Return value: + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->set_phb_mem_window) + return OPAL_UNSUPPORTED; diff --git a/doc/opal-api/opal-pci-set-phb-mem-window-28.txt b/doc/opal-api/opal-pci-set-phb-mem-window-28.txt deleted file mode 100644 index 8a355e8..0000000 --- a/doc/opal-api/opal-pci-set-phb-mem-window-28.txt +++ /dev/null @@ -1,71 +0,0 @@ -OPAL_PCI_SET_PHB_MEM_WINDOW ---------------------------- - -#define OPAL_PCI_SET_PHB_MEM_WINDOW 28 - -static int64_t opal_pci_set_phb_mem_window(uint64_t phb_id, - uint16_t window_type, - uint16_t window_num, - uint64_t addr, - uint64_t pci_addr, - uint64_t size) - -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 PHB PCI memory window parameters for -PHBs. OPAL sets IO space for P7IOC and KVM cannot relocate this. KVM should -changes these windows only while all devices below the PHB are disabled for -PCI memory ops, and with the target window in disabled state (where supported -by PHB hardware). - - phb_id is the value from the PHB node ibm,opal-phbid property. - - window_type specifies 32-bit or 64-bit PCI memory - - '0' selects IO space, and is not supported for relocation. OPAL - returns OPAL_UNSUPPORTED for this value. - - '1' selects 32-bit PCI memory space - - '2' selects 64 bit PCI memory space - - window_num is the MMIO window number within the specified PCI memory space - - starting_real_address specifies the location within sytsem (processor)real - address space this MMIO window starts. This must be a location within the - IO Hub or PHB node ibm,opal-mmio-real property. - - starting_pci_address specifies the location within PCI 32 or 64-bit - address space that this MMIO window starts. For 64-bit PCI memory, this - must be within the low order 60 bit (1 Exabyte) region of PCI memory. - Addresses above 1EB are reserved to IODA definitions. - - segment_size defines the segment size of this window, in the same format - as and a matching value from the ibm,opal-memwin32/64 - property. The window total size, in bytes, is the segment_size times the - ibm,opal-memwin32/64 property and must not extend beyond - the ibm,opal-mmio-real property range within system real address space. - The total MMIO window size is the segment_size times the num_segments - supported for the specifice window. The host must assure that the - cumulative address space for all enabled windows does not exceed the total - PHB 32-bit or 64-bit real address window space, or extend outside these - address ranges, and that no windows overlap each other in real or PCI - address space. OPAL does not validate those conditions. - -A segment size of '0' indicates to disable this MMIO window. If the PHB -hardware does not support disabling a window, OPAL returns OPAL_UNSUPPORTED -status. - -The size of the system real and PCI memory spaces are equal and defined by -segment_size times the number of segments within this MMIO window. - -The host must set PHB memory windows to be within the system real address -ranges indicated in the PHB parent HDT hub node ibm,opal-mmio-real property. - -Return value: - if (!phb) - return OPAL_PARAMETER; - if (!phb->ops->set_phb_mem_window) - return OPAL_UNSUPPORTED; diff --git a/doc/opal-api/opal-pci-set-power-state-121.rst b/doc/opal-api/opal-pci-set-power-state-121.rst new file mode 100644 index 0000000..92da235 --- /dev/null +++ b/doc/opal-api/opal-pci-set-power-state-121.rst @@ -0,0 +1,36 @@ +OPAL_PCI_SET_POWER_STATE +--------------------------- + +Set PCI slot power state + +Parameters: + uint64_t async_token: Token of asynchronous message to be sent + on completion of OPAL_PCI_SLOT_POWER_{OFF, ON}. It is + ignored when @data is OPAL_PCI_SLOT_{OFFLINE, ONLINE}. + uint64_t id: PCI slot ID + uint64_t data: memory buffer pointer for the power state which + can be one of OPAL_PCI_SLOT_POWER_{OFF, ON, OFFLINE, ONLINE}. + +Calling: + +Set PCI slot's power state. The power state is stored in buffer pointed +by @data. The typical use is to hot add or remove adapters behind the +indicated PCI slot (by @id) in PCI hotplug path. + +User will receive an asychronous message after calling the API. The message +contains the API completion status: event (Power off or on), device node's +phandle identifying the PCI slot, errcode (e.g. OPAL_SUCCESS). The API returns +OPAL_ASYNC_COMPLETION for the case. + +The states OPAL_PCI_SLOT_OFFLINE and OPAL_PCI_SLOT_ONLINE are used for removing +or adding devices behind the slot. The device nodes in the device tree are +removed or added accordingly, without actually changing the slot's power state. +The API call will return OPAL_SUCCESS immediately and no further asynchronous +message will be sent. + +Return Codes: + +OPAL_SUCCESS - PCI hotplug on the slot is completed successfully +OPAL_ASYNC_COMPLETION - PCI hotplug needs further message to confirm +OPAL_PARAMETER - The indicated PCI slot isn't found +OPAL_UNSUPPORTED - Setting power state not supported on the PCI slot diff --git a/doc/opal-api/opal-pci-set-power-state-121.txt b/doc/opal-api/opal-pci-set-power-state-121.txt deleted file mode 100644 index 92da235..0000000 --- a/doc/opal-api/opal-pci-set-power-state-121.txt +++ /dev/null @@ -1,36 +0,0 @@ -OPAL_PCI_SET_POWER_STATE ---------------------------- - -Set PCI slot power state - -Parameters: - uint64_t async_token: Token of asynchronous message to be sent - on completion of OPAL_PCI_SLOT_POWER_{OFF, ON}. It is - ignored when @data is OPAL_PCI_SLOT_{OFFLINE, ONLINE}. - uint64_t id: PCI slot ID - uint64_t data: memory buffer pointer for the power state which - can be one of OPAL_PCI_SLOT_POWER_{OFF, ON, OFFLINE, ONLINE}. - -Calling: - -Set PCI slot's power state. The power state is stored in buffer pointed -by @data. The typical use is to hot add or remove adapters behind the -indicated PCI slot (by @id) in PCI hotplug path. - -User will receive an asychronous message after calling the API. The message -contains the API completion status: event (Power off or on), device node's -phandle identifying the PCI slot, errcode (e.g. OPAL_SUCCESS). The API returns -OPAL_ASYNC_COMPLETION for the case. - -The states OPAL_PCI_SLOT_OFFLINE and OPAL_PCI_SLOT_ONLINE are used for removing -or adding devices behind the slot. The device nodes in the device tree are -removed or added accordingly, without actually changing the slot's power state. -The API call will return OPAL_SUCCESS immediately and no further asynchronous -message will be sent. - -Return Codes: - -OPAL_SUCCESS - PCI hotplug on the slot is completed successfully -OPAL_ASYNC_COMPLETION - PCI hotplug needs further message to confirm -OPAL_PARAMETER - The indicated PCI slot isn't found -OPAL_UNSUPPORTED - Setting power state not supported on the PCI slot diff --git a/doc/opal-api/opal-pci-set-xive-pe-37.rst b/doc/opal-api/opal-pci-set-xive-pe-37.rst new file mode 100644 index 0000000..e37d65c --- /dev/null +++ b/doc/opal-api/opal-pci-set-xive-pe-37.rst @@ -0,0 +1,30 @@ +OPAL_PCI_SET_XIVE_PE +-------------------- + +static int64_t opal_pci_set_xive_pe(uint64_t phb_id, uint32_t pe_number, + uint32_t xive_num) + +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 bind a PE to an XIVE. Only that PE may then +signal an MSI that selects this XIVE. + + The phb_id parameter is the value from the PHB node ibm,opal-phbid + property. + + the pe_number is the index of a PE, from 0 to ibm,opal-num-pes minus 1. + + The xive_number is the index, from 0 to ibm,opal,ibm-num-msis minus + (num_lsis+1) + + This call maps the XIVR indexed by xive_num to the PE specified by + pe_number. For ibm,opal-ioda HW, the pe_number must match the pe_number + set in the MVE. + +Return value: + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->set_xive_pe) + return OPAL_UNSUPPORTED; diff --git a/doc/opal-api/opal-pci-set-xive-pe-37.txt b/doc/opal-api/opal-pci-set-xive-pe-37.txt deleted file mode 100644 index e37d65c..0000000 --- a/doc/opal-api/opal-pci-set-xive-pe-37.txt +++ /dev/null @@ -1,30 +0,0 @@ -OPAL_PCI_SET_XIVE_PE --------------------- - -static int64_t opal_pci_set_xive_pe(uint64_t phb_id, uint32_t pe_number, - uint32_t xive_num) - -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 bind a PE to an XIVE. Only that PE may then -signal an MSI that selects this XIVE. - - The phb_id parameter is the value from the PHB node ibm,opal-phbid - property. - - the pe_number is the index of a PE, from 0 to ibm,opal-num-pes minus 1. - - The xive_number is the index, from 0 to ibm,opal,ibm-num-msis minus - (num_lsis+1) - - This call maps the XIVR indexed by xive_num to the PE specified by - pe_number. For ibm,opal-ioda HW, the pe_number must match the pe_number - set in the MVE. - -Return value: - if (!phb) - return OPAL_PARAMETER; - if (!phb->ops->set_xive_pe) - return OPAL_UNSUPPORTED; diff --git a/doc/opal-api/opal-pci-tce-kill-126.rst b/doc/opal-api/opal-pci-tce-kill-126.rst new file mode 100644 index 0000000..e774966 --- /dev/null +++ b/doc/opal-api/opal-pci-tce-kill-126.rst @@ -0,0 +1,55 @@ +OPAL_PCI_TCE_KILL +----------------- + +int64_t opal_pci_tce_kill(uint64_t phb_id, + uint32_t kill_type, + uint32_t pe_num, + uint32_t tce_size, + uint64_t dma_addr, + uint32_t npages) + +An abstraction around TCE kill. This allows host OS kernels to use an OPAL +call if they don't know the model specific invalidation method. + +Where kill_type is one of: +enum { + OPAL_PCI_TCE_KILL_PAGES, + OPAL_PCI_TCE_KILL_PE, + OPAL_PCI_TCE_KILL_ALL, +}; + +Not all PHB types currently support this abstraction. It is supported in +PHB4, which means from POWER9 onwards it will be present. + +Returns: +OPAL_PARAMETER: if phb_id is invalid (or similar) +OPAL_UNSUPPORTED: if PHB model doesn't support this call. This is likely + true for systems before POWER9/PHB4. + Do *NOT* rely on this call existing for systems prior to + POWER9 (i.e. PHB4). + +Example code (from linux/arch/powerpc/platforms/powernv/pci-ioda.c) + +static inline void pnv_pci_ioda2_tce_invalidate_pe(struct pnv_ioda_pe *pe) +{ + struct pnv_phb *phb = pe->phb; + + if (phb->model == PNV_PHB_MODEL_PHB3 && phb->regs) + pnv_pci_phb3_tce_invalidate_pe(pe); + else + opal_pci_tce_kill(phb->opal_id, OPAL_PCI_TCE_KILL_PE, + pe->pe_number, 0, 0, 0); +} + +and + +struct pnv_phb *phb = pe->phb; +unsigned int shift = tbl->it_page_shift; +if (phb->model == PNV_PHB_MODEL_PHB3 && phb->regs) + pnv_pci_phb3_tce_invalidate(pe, rm, shift, + index, npages); +else + opal_pci_tce_kill(phb->opal_id, + OPAL_PCI_TCE_KILL_PAGES, + pe->pe_number, 1u << shift, + index << shift, npages); diff --git a/doc/opal-api/opal-pci-tce-kill-126.txt b/doc/opal-api/opal-pci-tce-kill-126.txt deleted file mode 100644 index e774966..0000000 --- a/doc/opal-api/opal-pci-tce-kill-126.txt +++ /dev/null @@ -1,55 +0,0 @@ -OPAL_PCI_TCE_KILL ------------------ - -int64_t opal_pci_tce_kill(uint64_t phb_id, - uint32_t kill_type, - uint32_t pe_num, - uint32_t tce_size, - uint64_t dma_addr, - uint32_t npages) - -An abstraction around TCE kill. This allows host OS kernels to use an OPAL -call if they don't know the model specific invalidation method. - -Where kill_type is one of: -enum { - OPAL_PCI_TCE_KILL_PAGES, - OPAL_PCI_TCE_KILL_PE, - OPAL_PCI_TCE_KILL_ALL, -}; - -Not all PHB types currently support this abstraction. It is supported in -PHB4, which means from POWER9 onwards it will be present. - -Returns: -OPAL_PARAMETER: if phb_id is invalid (or similar) -OPAL_UNSUPPORTED: if PHB model doesn't support this call. This is likely - true for systems before POWER9/PHB4. - Do *NOT* rely on this call existing for systems prior to - POWER9 (i.e. PHB4). - -Example code (from linux/arch/powerpc/platforms/powernv/pci-ioda.c) - -static inline void pnv_pci_ioda2_tce_invalidate_pe(struct pnv_ioda_pe *pe) -{ - struct pnv_phb *phb = pe->phb; - - if (phb->model == PNV_PHB_MODEL_PHB3 && phb->regs) - pnv_pci_phb3_tce_invalidate_pe(pe); - else - opal_pci_tce_kill(phb->opal_id, OPAL_PCI_TCE_KILL_PE, - pe->pe_number, 0, 0, 0); -} - -and - -struct pnv_phb *phb = pe->phb; -unsigned int shift = tbl->it_page_shift; -if (phb->model == PNV_PHB_MODEL_PHB3 && phb->regs) - pnv_pci_phb3_tce_invalidate(pe, rm, shift, - index, npages); -else - opal_pci_tce_kill(phb->opal_id, - OPAL_PCI_TCE_KILL_PAGES, - pe->pe_number, 1u << shift, - index << shift, npages); diff --git a/doc/opal-api/opal-poll-events.rst b/doc/opal-api/opal-poll-events.rst new file mode 100644 index 0000000..6a0832e --- /dev/null +++ b/doc/opal-api/opal-poll-events.rst @@ -0,0 +1,84 @@ +OPAL_POLL_EVENTS +---------------- + +Poll for outstanding events. + +Fills in a bitmask of pending events. + +Current events are: + +OPAL_EVENT_OPAL_INTERNAL = 0x1 +------------------------------ +Currently unused. + + +OPAL_EVENT_NVRAM = 0x2 +---------------------- +Unused + + +OPAL_EVENT_RTC = 0x4 +-------------------- + +TODO: clean this up, this is just copied from hw/fsp/fsp-rtc.c: + + * Because the RTC calls can be pretty slow, these functions will shoot + * an asynchronous request to the FSP (if none is already pending) + * + * The requests will return OPAL_BUSY_EVENT as long as the event has + * not been completed. + * + * WARNING: An attempt at doing an RTC write while one is already pending + * will simply ignore the new arguments and continue returning + * OPAL_BUSY_EVENT. This is to be compatible with existing Linux code. + * + * Completion of the request will result in an event OPAL_EVENT_RTC + * being signaled, which will remain raised until a corresponding call + * to opal_rtc_read() or opal_rtc_write() finally returns OPAL_SUCCESS, + * at which point the operation is complete and the event cleared. + * + * If we end up taking longer than rtc_read_timeout_ms millieconds waiting + * for the response from a read request, we simply return a cached value (plus + * an offset calculated from the timebase. When the read request finally + * returns, we update our cache value accordingly. + * + * There is two separate set of state for reads and writes. If both are + * attempted at the same time, the event bit will remain set as long as either + * of the two has a pending event to signal. + + + +OPAL_EVENT_CONSOLE_OUTPUT = 0x8 +------------------------------- +TODO + +OPAL_EVENT_CONSOLE_INPUT = 0x10 +------------------------------- +TODO + +OPAL_EVENT_ERROR_LOG_AVAIL = 0x20 +--------------------------------- +TODO + +OPAL_EVENT_ERROR_LOG = 0x40 +--------------------------- +TODO + +OPAL_EVENT_EPOW = 0x80 +---------------------- +TODO + +OPAL_EVENT_LED_STATUS = 0x100 +----------------------------- +TODO + +OPAL_EVENT_PCI_ERROR = 0x200 +---------------------------- +TODO + +OPAL_EVENT_DUMP_AVAIL = 0x400 +----------------------------- +Signifies that there is a pending system dump available. See OPAL_DUMP suite +of calls for details. + +OPAL_EVENT_MSG_PENDING = 0x800, diff --git a/doc/opal-api/opal-poll-events.txt b/doc/opal-api/opal-poll-events.txt deleted file mode 100644 index 6a0832e..0000000 --- a/doc/opal-api/opal-poll-events.txt +++ /dev/null @@ -1,84 +0,0 @@ -OPAL_POLL_EVENTS ----------------- - -Poll for outstanding events. - -Fills in a bitmask of pending events. - -Current events are: - -OPAL_EVENT_OPAL_INTERNAL = 0x1 ------------------------------- -Currently unused. - - -OPAL_EVENT_NVRAM = 0x2 ----------------------- -Unused - - -OPAL_EVENT_RTC = 0x4 --------------------- - -TODO: clean this up, this is just copied from hw/fsp/fsp-rtc.c: - - * Because the RTC calls can be pretty slow, these functions will shoot - * an asynchronous request to the FSP (if none is already pending) - * - * The requests will return OPAL_BUSY_EVENT as long as the event has - * not been completed. - * - * WARNING: An attempt at doing an RTC write while one is already pending - * will simply ignore the new arguments and continue returning - * OPAL_BUSY_EVENT. This is to be compatible with existing Linux code. - * - * Completion of the request will result in an event OPAL_EVENT_RTC - * being signaled, which will remain raised until a corresponding call - * to opal_rtc_read() or opal_rtc_write() finally returns OPAL_SUCCESS, - * at which point the operation is complete and the event cleared. - * - * If we end up taking longer than rtc_read_timeout_ms millieconds waiting - * for the response from a read request, we simply return a cached value (plus - * an offset calculated from the timebase. When the read request finally - * returns, we update our cache value accordingly. - * - * There is two separate set of state for reads and writes. If both are - * attempted at the same time, the event bit will remain set as long as either - * of the two has a pending event to signal. - - - -OPAL_EVENT_CONSOLE_OUTPUT = 0x8 -------------------------------- -TODO - -OPAL_EVENT_CONSOLE_INPUT = 0x10 -------------------------------- -TODO - -OPAL_EVENT_ERROR_LOG_AVAIL = 0x20 ---------------------------------- -TODO - -OPAL_EVENT_ERROR_LOG = 0x40 ---------------------------- -TODO - -OPAL_EVENT_EPOW = 0x80 ----------------------- -TODO - -OPAL_EVENT_LED_STATUS = 0x100 ------------------------------ -TODO - -OPAL_EVENT_PCI_ERROR = 0x200 ----------------------------- -TODO - -OPAL_EVENT_DUMP_AVAIL = 0x400 ------------------------------ -Signifies that there is a pending system dump available. See OPAL_DUMP suite -of calls for details. - -OPAL_EVENT_MSG_PENDING = 0x800, diff --git a/doc/opal-api/opal-prd-msg-113.rst b/doc/opal-api/opal-prd-msg-113.rst new file mode 100644 index 0000000..b41f17e --- /dev/null +++ b/doc/opal-api/opal-prd-msg-113.rst @@ -0,0 +1,11 @@ + +OPAL_PRD_MSG call +------------- + +The OPAL_PRD_MSG call is used to pass a struct opal_prd_msg from the HBRT +code into opal, and is paired with the OPAL_PRD_MSG message type. + +Parameters: + struct opal_msg *msg + +Passes an opal_msg, of type OPAL_PRD_MSG, from the OS to OPAL. diff --git a/doc/opal-api/opal-prd-msg-113.txt b/doc/opal-api/opal-prd-msg-113.txt deleted file mode 100644 index b41f17e..0000000 --- a/doc/opal-api/opal-prd-msg-113.txt +++ /dev/null @@ -1,11 +0,0 @@ - -OPAL_PRD_MSG call -------------- - -The OPAL_PRD_MSG call is used to pass a struct opal_prd_msg from the HBRT -code into opal, and is paired with the OPAL_PRD_MSG message type. - -Parameters: - struct opal_msg *msg - -Passes an opal_msg, of type OPAL_PRD_MSG, from the OS to OPAL. diff --git a/doc/opal-api/opal-read-write-tpo-103-104.rst b/doc/opal-api/opal-read-write-tpo-103-104.rst new file mode 100644 index 0000000..0040615 --- /dev/null +++ b/doc/opal-api/opal-read-write-tpo-103-104.rst @@ -0,0 +1,15 @@ +OPAL_READ_TPO and OPAL_WRITE_TPO +-------------------------------- + +TPO is a Timed Power On facility. + +It is an OPTIONAL part of the OPAL spec. + +If a platform supports Timed Power On (TPO), the RTC node in the device tree (itself under the "ibm,opal" node will have the has-tpo property: + +rtc { + compatible = "ibm,opal-rtc"; + has-tpo; +}; + +If the "has-tpo" proprety is *NOT* present then OPAL does *NOT* support TPO. diff --git a/doc/opal-api/opal-read-write-tpo-103-104.txt b/doc/opal-api/opal-read-write-tpo-103-104.txt deleted file mode 100644 index 0040615..0000000 --- a/doc/opal-api/opal-read-write-tpo-103-104.txt +++ /dev/null @@ -1,15 +0,0 @@ -OPAL_READ_TPO and OPAL_WRITE_TPO --------------------------------- - -TPO is a Timed Power On facility. - -It is an OPTIONAL part of the OPAL spec. - -If a platform supports Timed Power On (TPO), the RTC node in the device tree (itself under the "ibm,opal" node will have the has-tpo property: - -rtc { - compatible = "ibm,opal-rtc"; - has-tpo; -}; - -If the "has-tpo" proprety is *NOT* present then OPAL does *NOT* support TPO. diff --git a/doc/opal-api/opal-register-dump-region-101.rst b/doc/opal-api/opal-register-dump-region-101.rst new file mode 100644 index 0000000..e88e8cf --- /dev/null +++ b/doc/opal-api/opal-register-dump-region-101.rst @@ -0,0 +1,43 @@ +OPAL_REGISTER_DUMP_REGION +------------------------- + +This call is used to register regions of memory for a service processor to capture +when the host crashes. + +e.g. if an assert is hit in OPAL, a service processor will copy + +This is an OPTIONAL feature that may be unsupported, the host OS should use an +OPAL_CHECK_TOKEN call to find out if OPAL_REGISTER_DUMP_REGION is supported. + +OPAL_REGISTER_DUMP_REGION accepts 3 parameters: +- region ID +- address +- length + +There is a range of region IDs that can be used by the host OS. A host OS should +start from OPAL_DUMP_REGION_HOST_END and work down if it wants to add a not well +defined region to dump. Currently the only well defined region is for the host +OS log buffer (e.g. dmesg on linux). + +/* + * Dump region ID range usable by the OS + */ +#define OPAL_DUMP_REGION_HOST_START 0x80 +#define OPAL_DUMP_REGION_LOG_BUF 0x80 +#define OPAL_DUMP_REGION_HOST_END 0xFF + +OPAL_REGISTER_DUMP_REGION will return OPAL_UNSUPPORTED if the call is present but +the system doesn't support registering regions to be dumped. + +In the event of being passed an invalid region ID, OPAL_REGISTER_DUMP_REGION will +return OPAL_PARAMETER. + +Systems likely have a limit as to how many regions they can support being dumped. If +this limit is reached, OPAL_REGISTER_DUMP_REGION will return OPAL_INTERNAL_ERROR. + +BUGS: +Some skiboot versions incorrectly returned OPAL_SUCCESS in the case of +OPAL_REGISTER_DUMP_REGION being supported on a platform (so the call was present) +but the call being unsupported for some reason (e.g. on an IBM POWER7 machine). + +See also: OPAL_UNREGISTER_DUMP_REGION diff --git a/doc/opal-api/opal-register-dump-region-101.txt b/doc/opal-api/opal-register-dump-region-101.txt deleted file mode 100644 index e88e8cf..0000000 --- a/doc/opal-api/opal-register-dump-region-101.txt +++ /dev/null @@ -1,43 +0,0 @@ -OPAL_REGISTER_DUMP_REGION -------------------------- - -This call is used to register regions of memory for a service processor to capture -when the host crashes. - -e.g. if an assert is hit in OPAL, a service processor will copy - -This is an OPTIONAL feature that may be unsupported, the host OS should use an -OPAL_CHECK_TOKEN call to find out if OPAL_REGISTER_DUMP_REGION is supported. - -OPAL_REGISTER_DUMP_REGION accepts 3 parameters: -- region ID -- address -- length - -There is a range of region IDs that can be used by the host OS. A host OS should -start from OPAL_DUMP_REGION_HOST_END and work down if it wants to add a not well -defined region to dump. Currently the only well defined region is for the host -OS log buffer (e.g. dmesg on linux). - -/* - * Dump region ID range usable by the OS - */ -#define OPAL_DUMP_REGION_HOST_START 0x80 -#define OPAL_DUMP_REGION_LOG_BUF 0x80 -#define OPAL_DUMP_REGION_HOST_END 0xFF - -OPAL_REGISTER_DUMP_REGION will return OPAL_UNSUPPORTED if the call is present but -the system doesn't support registering regions to be dumped. - -In the event of being passed an invalid region ID, OPAL_REGISTER_DUMP_REGION will -return OPAL_PARAMETER. - -Systems likely have a limit as to how many regions they can support being dumped. If -this limit is reached, OPAL_REGISTER_DUMP_REGION will return OPAL_INTERNAL_ERROR. - -BUGS: -Some skiboot versions incorrectly returned OPAL_SUCCESS in the case of -OPAL_REGISTER_DUMP_REGION being supported on a platform (so the call was present) -but the call being unsupported for some reason (e.g. on an IBM POWER7 machine). - -See also: OPAL_UNREGISTER_DUMP_REGION diff --git a/doc/opal-api/opal-reinit-cpus-70.rst b/doc/opal-api/opal-reinit-cpus-70.rst new file mode 100644 index 0000000..bf9b238 --- /dev/null +++ b/doc/opal-api/opal-reinit-cpus-70.rst @@ -0,0 +1,29 @@ +OPAL_REINIT_CPUS +---------------- + +static int64_t opal_reinit_cpus(uint64_t flags); + +This OPAL call reinitializes some bit of CPU state across *ALL* CPUs. +Consequently, all CPUs must be in OPAL for this call to succeed (either +at boot time or after OPAL_RETURN_CPU is called) + +Arguments: +Currently, possible flags are: +enum { + OPAL_REINIT_CPUS_HILE_BE = (1 << 0), + OPAL_REINIT_CPUS_HILE_LE = (1 << 1), +}; + +Extra flags may be added in the future, so other bits *must* be 0. + +On POWER7 CPUs, only OPAL_REINIT_CPUS_HILE_BE is supported. All other +flags will return OPAL_UNSUPPORTED. + +On POWER8 CPUs, only OPAL_REINIT_CPUS_HILE_BE and OPAL_REINIT_CPUS_HILE_LE +are support and other bits *MUST NOT* be set. + +On POWER9 CPUs, other flags may be supported in the future. + +Returns: +- OPAL_SUCCESS +- OPAL_UNSUPPORTED diff --git a/doc/opal-api/opal-reinit-cpus-70.txt b/doc/opal-api/opal-reinit-cpus-70.txt deleted file mode 100644 index bf9b238..0000000 --- a/doc/opal-api/opal-reinit-cpus-70.txt +++ /dev/null @@ -1,29 +0,0 @@ -OPAL_REINIT_CPUS ----------------- - -static int64_t opal_reinit_cpus(uint64_t flags); - -This OPAL call reinitializes some bit of CPU state across *ALL* CPUs. -Consequently, all CPUs must be in OPAL for this call to succeed (either -at boot time or after OPAL_RETURN_CPU is called) - -Arguments: -Currently, possible flags are: -enum { - OPAL_REINIT_CPUS_HILE_BE = (1 << 0), - OPAL_REINIT_CPUS_HILE_LE = (1 << 1), -}; - -Extra flags may be added in the future, so other bits *must* be 0. - -On POWER7 CPUs, only OPAL_REINIT_CPUS_HILE_BE is supported. All other -flags will return OPAL_UNSUPPORTED. - -On POWER8 CPUs, only OPAL_REINIT_CPUS_HILE_BE and OPAL_REINIT_CPUS_HILE_LE -are support and other bits *MUST NOT* be set. - -On POWER9 CPUs, other flags may be supported in the future. - -Returns: -- OPAL_SUCCESS -- OPAL_UNSUPPORTED diff --git a/doc/opal-api/opal-return-cpu-69.rst b/doc/opal-api/opal-return-cpu-69.rst new file mode 100644 index 0000000..db54cae --- /dev/null +++ b/doc/opal-api/opal-return-cpu-69.rst @@ -0,0 +1,17 @@ +OPAL_RETURN_CPU +--------------- + +int64_t opal_return_cpu(void); + +When OPAL first starts the host, all secondary CPUs are spinning in OPAL. +To start them, one must call OPAL_START_CPU (you may want to OPAL_REINIT_CPU +to set the HILE bit first). + +In cases where you need OPAL to do something for you across all CPUs, such +as OPAL_REINIT_CPU, (on some platforms) a firmware update or get the machine +back into a similar state as to when the host OS was started (e.g. for kexec) +you may also need to return control of the CPU to OPAL. + + +Returns: +- this call does not return. You need to OPAL_START_CPU. diff --git a/doc/opal-api/opal-return-cpu-69.txt b/doc/opal-api/opal-return-cpu-69.txt deleted file mode 100644 index db54cae..0000000 --- a/doc/opal-api/opal-return-cpu-69.txt +++ /dev/null @@ -1,17 +0,0 @@ -OPAL_RETURN_CPU ---------------- - -int64_t opal_return_cpu(void); - -When OPAL first starts the host, all secondary CPUs are spinning in OPAL. -To start them, one must call OPAL_START_CPU (you may want to OPAL_REINIT_CPU -to set the HILE bit first). - -In cases where you need OPAL to do something for you across all CPUs, such -as OPAL_REINIT_CPU, (on some platforms) a firmware update or get the machine -back into a similar state as to when the host OS was started (e.g. for kexec) -you may also need to return control of the CPU to OPAL. - - -Returns: -- this call does not return. You need to OPAL_START_CPU. diff --git a/doc/opal-api/opal-rtc-read-3.rst b/doc/opal-api/opal-rtc-read-3.rst new file mode 100644 index 0000000..13a0655 --- /dev/null +++ b/doc/opal-api/opal-rtc-read-3.rst @@ -0,0 +1,55 @@ +OPAL_RTC_READ +------------- + +Read the Real Time Clock. + +Parameters: + uint32_t* year_month_day: the year, month and day formatted as follows: + - bits 0-15 is bcd formatted year (0100-9999) + - bits 16-23 is bcd formatted month (01-12) + - bits 24-31 is bcd formatted day (01-31) + uint64_t* hour_minute_second_millisecond: the hour, minute, second + and millisecond formatted as follows: + - bits 0-16 is reserved + - bits 17-24 is bcd formatted hour (00-23) + - bits 25-31 is bcd formatted minute (00-59) + - bits 32-39 is bcd formatted second (00-60) + - bits 40-63 is bcd formatted milliseconds (000000-999999) + +Calling: + +Since RTC calls can be pretty slow, OPAL_RTC_READ is likely to first return +OPAL_BUSY_EVENT, requiring the caller to wait until the OPAL_EVENT_RTC event +has been signaled. Once the event has been signaled, a subsequent +OPAL_RTC_READ call will retrieve the time. Since the OPAL_EVENT_RTC event is +used for both reading and writing the RTC, callers must be able to handle +the event being signaled for a concurrent in flight OPAL_RTC_WRITE rather +than this read request. + +The following code is one way to correctly issue and then wait for a response: + + int rc = OPAL_BUSY_EVENT; + while (rc == OPAL_BUSY_EVENT) { + rc = opal_rtc_read(&y_m_d, &h_m_s_ms); + if (rc == OPAL_BUSY_EVENT) + opal_poll_events(NULL); + } + +Although as of writing all OPAL_RTC_READ backends are asynchronous, there is +no requirement for them to be - it is valid for OPAL_RTC_READ to immediately +return the retreived value rather than OPAL_BUSY_EVENT. + +TODO: describe/document format of arguments. + +Return codes: +OPAL_SUCCESS: + - parameters now contain the current time, or one read from cache. +OPAL_HARDWARE: + - error in retrieving the time. May be transient error, + may be permanent. +OPAL_PARAMETER: + - year_month_day or hour_minute_second_millisecond parameters are NULL +OPAL_INTERNAL_ERROR: + - something went wrong, Possibly reported in error log. +OPAL_BUSY_EVENT: + - request is in flight diff --git a/doc/opal-api/opal-rtc-read-3.txt b/doc/opal-api/opal-rtc-read-3.txt deleted file mode 100644 index 13a0655..0000000 --- a/doc/opal-api/opal-rtc-read-3.txt +++ /dev/null @@ -1,55 +0,0 @@ -OPAL_RTC_READ -------------- - -Read the Real Time Clock. - -Parameters: - uint32_t* year_month_day: the year, month and day formatted as follows: - - bits 0-15 is bcd formatted year (0100-9999) - - bits 16-23 is bcd formatted month (01-12) - - bits 24-31 is bcd formatted day (01-31) - uint64_t* hour_minute_second_millisecond: the hour, minute, second - and millisecond formatted as follows: - - bits 0-16 is reserved - - bits 17-24 is bcd formatted hour (00-23) - - bits 25-31 is bcd formatted minute (00-59) - - bits 32-39 is bcd formatted second (00-60) - - bits 40-63 is bcd formatted milliseconds (000000-999999) - -Calling: - -Since RTC calls can be pretty slow, OPAL_RTC_READ is likely to first return -OPAL_BUSY_EVENT, requiring the caller to wait until the OPAL_EVENT_RTC event -has been signaled. Once the event has been signaled, a subsequent -OPAL_RTC_READ call will retrieve the time. Since the OPAL_EVENT_RTC event is -used for both reading and writing the RTC, callers must be able to handle -the event being signaled for a concurrent in flight OPAL_RTC_WRITE rather -than this read request. - -The following code is one way to correctly issue and then wait for a response: - - int rc = OPAL_BUSY_EVENT; - while (rc == OPAL_BUSY_EVENT) { - rc = opal_rtc_read(&y_m_d, &h_m_s_ms); - if (rc == OPAL_BUSY_EVENT) - opal_poll_events(NULL); - } - -Although as of writing all OPAL_RTC_READ backends are asynchronous, there is -no requirement for them to be - it is valid for OPAL_RTC_READ to immediately -return the retreived value rather than OPAL_BUSY_EVENT. - -TODO: describe/document format of arguments. - -Return codes: -OPAL_SUCCESS: - - parameters now contain the current time, or one read from cache. -OPAL_HARDWARE: - - error in retrieving the time. May be transient error, - may be permanent. -OPAL_PARAMETER: - - year_month_day or hour_minute_second_millisecond parameters are NULL -OPAL_INTERNAL_ERROR: - - something went wrong, Possibly reported in error log. -OPAL_BUSY_EVENT: - - request is in flight diff --git a/doc/opal-api/opal-rtc-write-4.rst b/doc/opal-api/opal-rtc-write-4.rst new file mode 100644 index 0000000..37ca915 --- /dev/null +++ b/doc/opal-api/opal-rtc-write-4.rst @@ -0,0 +1,9 @@ +OPAL_RTC_WRITE +-------------- + +OPAL_RTC_WRITE is much like OPAL_RTC_READ in that it can be asynchronous. + +If multiple WRITES are issued before the first one completes, subsequent +writes are ignored. There can only be one write in flight at any one time. + +Format of the time is the same as for OPAL_RTC_READ. diff --git a/doc/opal-api/opal-rtc-write-4.txt b/doc/opal-api/opal-rtc-write-4.txt deleted file mode 100644 index 37ca915..0000000 --- a/doc/opal-api/opal-rtc-write-4.txt +++ /dev/null @@ -1,9 +0,0 @@ -OPAL_RTC_WRITE --------------- - -OPAL_RTC_WRITE is much like OPAL_RTC_READ in that it can be asynchronous. - -If multiple WRITES are issued before the first one completes, subsequent -writes are ignored. There can only be one write in flight at any one time. - -Format of the time is the same as for OPAL_RTC_READ. diff --git a/doc/opal-api/opal-sensor-read-88.rst b/doc/opal-api/opal-sensor-read-88.rst new file mode 100644 index 0000000..f6c62e1 --- /dev/null +++ b/doc/opal-api/opal-sensor-read-88.rst @@ -0,0 +1,33 @@ +OPAL_SENSOR_READ +---------------- + +The OPAL sensor call reads a sensor data using a unique handler to +identity the targeted sensor. + + +This call can be asynchronous, when a message needs to be sent to a +service processor for example. In this case, the call will return +OPAL_ASYNC_COMPLETION and the token parameter will be used to wait for +the completion of the request. + + +Parameters: + uint32_t sensor_handler + int token + uint32_t *sensor_data + + +Return values: + OPAL_SUCCESS + OPAL_PARAMETER - invalid sensor handler + OPAL_UNSUPPORTED - plateform does not support reading sensors. + +in case of communication with the FSP on IBM systems + + OPAL_ASYNC_COMPLETION - a request was sent and an async completion will + be triggered with the @token argument + OPAL_PARTIAL - the request completed but the data returned is invalid + OPAL_BUSY_EVENT - a previous request is still pending + OPAL_NO_MEM - allocation failed + OPAL_INTERNAL_ERROR - communication failure with the FSP + OPAL_HARDWARE - FSP is not available diff --git a/doc/opal-api/opal-sensor-read-88.txt b/doc/opal-api/opal-sensor-read-88.txt deleted file mode 100644 index f6c62e1..0000000 --- a/doc/opal-api/opal-sensor-read-88.txt +++ /dev/null @@ -1,33 +0,0 @@ -OPAL_SENSOR_READ ----------------- - -The OPAL sensor call reads a sensor data using a unique handler to -identity the targeted sensor. - - -This call can be asynchronous, when a message needs to be sent to a -service processor for example. In this case, the call will return -OPAL_ASYNC_COMPLETION and the token parameter will be used to wait for -the completion of the request. - - -Parameters: - uint32_t sensor_handler - int token - uint32_t *sensor_data - - -Return values: - OPAL_SUCCESS - OPAL_PARAMETER - invalid sensor handler - OPAL_UNSUPPORTED - plateform does not support reading sensors. - -in case of communication with the FSP on IBM systems - - OPAL_ASYNC_COMPLETION - a request was sent and an async completion will - be triggered with the @token argument - OPAL_PARTIAL - the request completed but the data returned is invalid - OPAL_BUSY_EVENT - a previous request is still pending - OPAL_NO_MEM - allocation failed - OPAL_INTERNAL_ERROR - communication failure with the FSP - OPAL_HARDWARE - FSP is not available diff --git a/doc/opal-api/opal-set-xive-19.rst b/doc/opal-api/opal-set-xive-19.rst new file mode 100644 index 0000000..590847b --- /dev/null +++ b/doc/opal-api/opal-set-xive-19.rst @@ -0,0 +1,24 @@ +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 POWER XIVE server and priority +parameters into the PHB XIVE. + + The phb_id parameter is the value from the PHB node ibm,opal-phbid + property. + + The xive_number is the index of an XIVE that corresponds to a particular + interrupt + + the service_number is the server (processor) that is to receive the + interrupt request + + the priority is the interrupt priority value applied to the interrupt + (0=highest, 0xFF = lowest/disabled). + diff --git a/doc/opal-api/opal-set-xive-19.txt b/doc/opal-api/opal-set-xive-19.txt deleted file mode 100644 index 590847b..0000000 --- a/doc/opal-api/opal-set-xive-19.txt +++ /dev/null @@ -1,24 +0,0 @@ -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 POWER XIVE server and priority -parameters into the PHB XIVE. - - The phb_id parameter is the value from the PHB node ibm,opal-phbid - property. - - The xive_number is the index of an XIVE that corresponds to a particular - interrupt - - the service_number is the server (processor) that is to receive the - interrupt request - - the priority is the interrupt priority value applied to the interrupt - (0=highest, 0xFF = lowest/disabled). - diff --git a/doc/opal-api/opal-sync-host-reboot-87.rst b/doc/opal-api/opal-sync-host-reboot-87.rst new file mode 100644 index 0000000..52d3776 --- /dev/null +++ b/doc/opal-api/opal-sync-host-reboot-87.rst @@ -0,0 +1,15 @@ +OPAL_SYNC_HOST_REBOOT +===================== + +static int64_t opal_sync_host_reboot(void) + +This OPAL call halts asynchronous operations in preparation for something +like kexec. It will halt DMA as well notification of some events (such +as a new error log being available for retreival). + +It's meant to be called in a loop until OPAL_SUCCESS is returned. + +Returns: +- OPAL_SUCCESS: Success! +- OPAL_BUSY_EVENT: not yet complete, call opal_sync_host_reboot() again, possibly with a short delay. +- OPAL_BUSY: Call opal_poll_events() and then retry opal_sync_host_reboot diff --git a/doc/opal-api/opal-sync-host-reboot-87.txt b/doc/opal-api/opal-sync-host-reboot-87.txt deleted file mode 100644 index 52d3776..0000000 --- a/doc/opal-api/opal-sync-host-reboot-87.txt +++ /dev/null @@ -1,15 +0,0 @@ -OPAL_SYNC_HOST_REBOOT -===================== - -static int64_t opal_sync_host_reboot(void) - -This OPAL call halts asynchronous operations in preparation for something -like kexec. It will halt DMA as well notification of some events (such -as a new error log being available for retreival). - -It's meant to be called in a loop until OPAL_SUCCESS is returned. - -Returns: -- OPAL_SUCCESS: Success! -- OPAL_BUSY_EVENT: not yet complete, call opal_sync_host_reboot() again, possibly with a short delay. -- OPAL_BUSY: Call opal_poll_events() and then retry opal_sync_host_reboot diff --git a/doc/opal-api/opal-test-0.rst b/doc/opal-api/opal-test-0.rst new file mode 100644 index 0000000..f732227 --- /dev/null +++ b/doc/opal-api/opal-test-0.rst @@ -0,0 +1,30 @@ +OPAL_TEST +--------- + +OPAL_TEST is a REQUIRED call for OPAL and conforming implementations MUST +have it. + +It is designed to test basic OPAL call functionality. + +Token: +#define OPAL_TEST 0 + +Arguments: + uint64_t arg + +Returns: + 0xfeedf00d + + +Function: +OPAL_TEST MAY print a string to the OPAL log with the value of argument. + +For example, the reference implementation (skiboot) implements OPAL_TEST as: + +static uint64_t opal_test_func(uint64_t arg) +{ + printf("OPAL: Test function called with arg 0x%llx\n", arg); + + return 0xfeedf00d; +} + diff --git a/doc/opal-api/opal-test-0.txt b/doc/opal-api/opal-test-0.txt deleted file mode 100644 index f732227..0000000 --- a/doc/opal-api/opal-test-0.txt +++ /dev/null @@ -1,30 +0,0 @@ -OPAL_TEST ---------- - -OPAL_TEST is a REQUIRED call for OPAL and conforming implementations MUST -have it. - -It is designed to test basic OPAL call functionality. - -Token: -#define OPAL_TEST 0 - -Arguments: - uint64_t arg - -Returns: - 0xfeedf00d - - -Function: -OPAL_TEST MAY print a string to the OPAL log with the value of argument. - -For example, the reference implementation (skiboot) implements OPAL_TEST as: - -static uint64_t opal_test_func(uint64_t arg) -{ - printf("OPAL: Test function called with arg 0x%llx\n", arg); - - return 0xfeedf00d; -} - diff --git a/doc/opal-api/opal-unregister-dump-region-102.rst b/doc/opal-api/opal-unregister-dump-region-102.rst new file mode 100644 index 0000000..268d501 --- /dev/null +++ b/doc/opal-api/opal-unregister-dump-region-102.rst @@ -0,0 +1,18 @@ +OPAL_UNREGISTER_DUMP_REGION +--------------------------- + +While OPAL_REGISTER_DUMP_REGION registers a region, OPAL_UNREGISTER_DUMP_REGION +will unregister a region by region ID. + +OPAL_UNREGISTER_DUMP_REGION takes one argument: the region ID. + +A host OS should check OPAL_UNREGISTER_DUMP_REGION is supported through a call to +OPAL_CHECK_TOKEN. + +If OPAL_UNREGISTER_DUMP_REGION is called on a system where the call is present but +unsupported, it will return OPAL_UNSUPPORTED. + +BUGS: +Some skiboot versions incorrectly returned OPAL_SUCCESS in the case of +OPAL_UNREGISTER_DUMP_REGION being supported on a platform (so the call was present) +but the call being unsupported for some reason (e.g. on an IBM POWER7 machine). diff --git a/doc/opal-api/opal-unregister-dump-region-102.txt b/doc/opal-api/opal-unregister-dump-region-102.txt deleted file mode 100644 index 268d501..0000000 --- a/doc/opal-api/opal-unregister-dump-region-102.txt +++ /dev/null @@ -1,18 +0,0 @@ -OPAL_UNREGISTER_DUMP_REGION ---------------------------- - -While OPAL_REGISTER_DUMP_REGION registers a region, OPAL_UNREGISTER_DUMP_REGION -will unregister a region by region ID. - -OPAL_UNREGISTER_DUMP_REGION takes one argument: the region ID. - -A host OS should check OPAL_UNREGISTER_DUMP_REGION is supported through a call to -OPAL_CHECK_TOKEN. - -If OPAL_UNREGISTER_DUMP_REGION is called on a system where the call is present but -unsupported, it will return OPAL_UNSUPPORTED. - -BUGS: -Some skiboot versions incorrectly returned OPAL_SUCCESS in the case of -OPAL_UNREGISTER_DUMP_REGION being supported on a platform (so the call was present) -but the call being unsupported for some reason (e.g. on an IBM POWER7 machine). diff --git a/doc/opal-api/opal-xscom-read-write-65-66.rst b/doc/opal-api/opal-xscom-read-write-65-66.rst new file mode 100644 index 0000000..4ed0134 --- /dev/null +++ b/doc/opal-api/opal-xscom-read-write-65-66.rst @@ -0,0 +1,17 @@ +OPAL_XSCOM_READ and OPAL_XSCOM_WRITE +------------------------------------ + +These low level calls will read/write XSCOM values directly. + +They should only be used by low level manufacturing/debug tools. +"Normal" host OS kernel code should not know about XSCOM. + +each takes three parameters: + +int xscom_read(uint32_t partid, uint64_t pcb_addr, uint64_t *val) +int xscom_write(uint32_t partid, uint64_t pcb_addr, uint64_t val) + +Returns: + OPAL_SUCCESS + OPAL_HARDWARE if operation failed + OPAL_WRONG_STATE if CPU is asleep diff --git a/doc/opal-api/opal-xscom-read-write-65-66.txt b/doc/opal-api/opal-xscom-read-write-65-66.txt deleted file mode 100644 index 4ed0134..0000000 --- a/doc/opal-api/opal-xscom-read-write-65-66.txt +++ /dev/null @@ -1,17 +0,0 @@ -OPAL_XSCOM_READ and OPAL_XSCOM_WRITE ------------------------------------- - -These low level calls will read/write XSCOM values directly. - -They should only be used by low level manufacturing/debug tools. -"Normal" host OS kernel code should not know about XSCOM. - -each takes three parameters: - -int xscom_read(uint32_t partid, uint64_t pcb_addr, uint64_t *val) -int xscom_write(uint32_t partid, uint64_t pcb_addr, uint64_t val) - -Returns: - OPAL_SUCCESS - OPAL_HARDWARE if operation failed - OPAL_WRONG_STATE if CPU is asleep