Add the final bits of old docs OPAL calls related to PCI

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

4 files changed, 241 insertions, 0 deletions

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
new file mode 100644
index 0000000..0793209
--- /dev/null
+++ b/doc/opal-api/opal-pci-map-pe-dma-window-44.txt
@@ -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-real-45.txt b/doc/opal-api/opal-pci-map-pe-dma-window-real-45.txt
new file mode 100644
index 0000000..28ea112
--- /dev/null
+++ b/doc/opal-api/opal-pci-map-pe-dma-window-real-45.txt
@@ -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-mmio-window-29.txt b/doc/opal-api/opal-pci-map-pe-mmio-window-29.txt
new file mode 100644
index 0000000..4f43506
--- /dev/null
+++ b/doc/opal-api/opal-pci-map-pe-mmio-window-29.txt
@@ -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-set-phb-mem-window-28.txt b/doc/opal-api/opal-pci-set-phb-mem-window-28.txt
new file mode 100644
index 0000000..8a355e8
--- /dev/null
+++ b/doc/opal-api/opal-pci-set-phb-mem-window-28.txt
@@ -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;