[Skiboot] [RFC PATCH 17/23] doc/opal-api: rename .txt to .rst
Stewart Smith
stewart at linux.vnet.ibm.com
Wed Jul 27 17:43:18 AEST 2016
Signed-off-by: Stewart Smith <stewart at linux.vnet.ibm.com>
---
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 at 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 at 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 OpalIo<PHBVer>ErrorData".
+
+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 OpalIo<PHBVer>ErrorData".
-
-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 <translation levels>.
+
+ 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
+ <dma-page-sizes>. 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 <translation levels>.
-
- 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
- <dma-page-sizes>. 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 <segment_size>
+ property. The window total size, in bytes, is the segment_size times the
+ ibm,opal-memwin32/64 <num_segments> 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 <segment_size>
- property. The window total size, in bytes, is the segment_size times the
- ibm,opal-memwin32/64 <num_segments> 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
--
2.7.4
More information about the Skiboot
mailing list