From 1b3384a20ceeadb5998d1208e4e16eb62693a0c4 Mon Sep 17 00:00:00 2001 From: Stewart Smith Date: Thu, 11 Jun 2015 09:02:57 +1000 Subject: 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 --- doc/opal-api/opal-pci-set-mve-33.txt | 36 ++++++++++++++ doc/opal-api/opal-pci-set-mve-enable-34.txt | 35 ++++++++++++++ doc/opal-api/opal-pci-set-pe-31.txt | 74 +++++++++++++++++++++++++++++ doc/opal-api/opal-pci-set-peltv-32.txt | 52 ++++++++++++++++++++ doc/opal-spec.txt | 7 +++ 5 files changed, 204 insertions(+) create mode 100644 doc/opal-api/opal-pci-set-mve-33.txt create mode 100644 doc/opal-api/opal-pci-set-mve-enable-34.txt create mode 100644 doc/opal-api/opal-pci-set-pe-31.txt create mode 100644 doc/opal-api/opal-pci-set-peltv-32.txt 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 ---------------- -- cgit v1.1