Add more OPAL documentation: MSI, XIVE, PHB MMIO

Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

4 files changed, 139 insertions, 0 deletions

diff --git a/doc/opal-api/opal-get-msi-39-40.txt b/doc/opal-api/opal-get-msi-39-40.txt
new file mode 100644
index 0000000..dbc809f
--- /dev/null
+++ b/doc/opal-api/opal-get-msi-39-40.txt
@@ -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-xive-20.txt b/doc/opal-api/opal-get-xive-20.txt
new file mode 100644
index 0000000..2a83cc8
--- /dev/null
+++ b/doc/opal-api/opal-get-xive-20.txt
@@ -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-pci-phb-mmio-enable-27.txt b/doc/opal-api/opal-pci-phb-mmio-enable-27.txt
new file mode 100644
index 0000000..c5b08f4
--- /dev/null
+++ b/doc/opal-api/opal-pci-phb-mmio-enable-27.txt
@@ -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 addres 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-set-xive-19.txt b/doc/opal-api/opal-set-xive-19.txt
new file mode 100644
index 0000000..590847b
--- /dev/null
+++ b/doc/opal-api/opal-set-xive-19.txt
@@ -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).
+