Add more documentation

Most of the PCI docs come from old documents and thus come with appropriate
warnings about accuracy. Much of this is designed to be a *starting point*
for real documentation.

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

5 files changed, 204 insertions, 0 deletions

diff --git a/doc/opal-api/opal-pci-set-mve-33.txt b/doc/opal-api/opal-pci-set-mve-33.txt
new file mode 100644
index 0000000..f407d41
--- /dev/null
+++ b/doc/opal-api/opal-pci-set-mve-33.txt
@@ -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-enable-34.txt b/doc/opal-api/opal-pci-set-mve-enable-34.txt
new file mode 100644
index 0000000..4c13d3c
--- /dev/null
+++ b/doc/opal-api/opal-pci-set-mve-enable-34.txt
@@ -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-pe-31.txt b/doc/opal-api/opal-pci-set-pe-31.txt
new file mode 100644
index 0000000..bfe3890
--- /dev/null
+++ b/doc/opal-api/opal-pci-set-pe-31.txt
@@ -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-peltv-32.txt b/doc/opal-api/opal-pci-set-peltv-32.txt
new file mode 100644
index 0000000..9274aab
--- /dev/null
+++ b/doc/opal-api/opal-pci-set-peltv-32.txt
@@ -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-spec.txt b/doc/opal-spec.txt
index 4cff78d..ea76e59 100644
--- a/doc/opal-spec.txt
+++ b/doc/opal-spec.txt
@@ -112,6 +112,13 @@ Explicitly allowed:
   (weather replacing skiroot with an implementation of Zork would be compliant
    is left as an exercise for the reader)
 
+Payload Environment
+-------------------
+The payload is started with:
+r3 = address of flattened device-tree (fdt)
+r8 = OPAL base
+r9 = OPAL entry
+
 
 Runtime Services
 ----------------