doc/device-tree: Add PCI bindings stub

Add a page for PCI device tree bindings. Right now it's just an example of
a PHB as seen on a POWER9 Zaius, and it could do with some extra
commentary.

Suggested-by: Stewart Smith <stewart@linux.vnet.ibm.com>
Signed-off-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com>
Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

2 files changed, 73 insertions, 0 deletions

diff --git a/doc/device-tree/pci.rst b/doc/device-tree/pci.rst
new file mode 100644
index 0000000..26707c5
--- /dev/null
+++ b/doc/device-tree/pci.rst
@@ -0,0 +1,68 @@
+.. _device-tree/pci:
+
+========================
+PCI Device Tree Bindings
+========================
+
+The following is an example PCI host bridge and device from a POWER9 machine.
+
+.. code-block:: dts
+
+  pciex@600c3c0300000 {
+    ibm,capi-flags = <0x1>;
+    ibm,phb-stack-index = <0x0>;
+    compatible = "ibm,power9-pciex", "ibm,ioda3-phb";
+    ibm,opal-single-pe;
+    ibm,opal-num-pes = <0x200>;
+    ibm,supported-tce-sizes = <0xc 0x10 0x15 0x1e>;
+    device_type = "pciex";
+    ibm,opal-peltv-table = <0x0 0x543c0000 0x20000>;
+    ibm,associativity = <0x4 0x0 0x0 0x1 0x0>;
+    ibm,phb-diag-data-size = <0x2180>;
+    ranges = <0x2000000 0x0 0x80000000 0x600c1 0x80000000 0x0 0x7fff0000>;
+    ibm,lane-eq = <0x54545454 0x54545454 0x54545454 0x54545454 0x54545454
+                   0x54545454 0x54545454 0x54545454 0x77777777 0x77777777
+		   0x77777777 0x77777777>;
+    status = "okay";
+    #interrupt-cells = <0x1>;
+    bus-range = <0x0 0xff>;
+    interrupt-parent = <0x126>;
+    #address-cells = <0x3>;
+    ibm,opal-phbid = <0x0 0x3>;
+    ibm,opal-pest-table = <0x0 0x543e2000 0x2000>;
+    ibm,chip-id = <0x0>;
+    #size-cells = <0x2>;
+    ibm,opal-m64-segment-splits = <0x200 0x1 0xc 0x0 0x1 0x2 0xc 0x0>;
+    ibm,opal-m64-window = <0x60200 0x0 0x60200 0x0 0x40 0x0>;
+    phandle = <0x617>;
+    ibm,phb-stack = <0xd8>;
+    ibm,phb-index = <0x3>;
+    reg = <0x600c3 0xc0300000 0x0 0x1000 0x600c3 0x60000000 0x0 0x10000000>;
+    ibm,mmio-windows = <0x60200 0x0 0x40 0x0 0x600c1 0x80000000 0x0 0x80000000>;
+    clock-frequency = <0x200 0x0>;
+    ibm,xscom-bases = <0x4011400 0x4011440 0xf010800 0xf010840 0xf010900>;
+    ibm,opal-reserved-pe = <0x1ff>;
+    ibm,capp-timebase-sync = [00];
+    ibm,opal-available-m64-ranges = <0x1 0x1f>;
+    ibm,opal-rtt-table = <0x0 0x54380000 0x20000>;
+    ibm,opal-msi-ranges = <0xfc000 0xff8>;
+
+    pci@0 {
+      device_type = "pciex";
+      revision-id = <0x0>;
+      ibm,pci-config-space-type = <0x1>;
+      interrupt-map-mask = <0x0 0x0 0x0 0x7>;
+      class-code = <0x60400>;
+      ranges = <0x2000000 0x0 0x0 0x2000000 0x0 0x0 0xf0000000 0x0>;
+      vendor-id = <0x1014>;
+      #interrupt-cells = <0x1>;
+      #address-cells = <0x3>;
+      interrupt-map = <0x0 0x0 0x0 0x1 0x126 0xfcff8 0x1 0x0 0x0 0x0 0x2 0x126
+                       0xfcff9 0x1 0x0 0x0 0x0 0x3 0x126 0xfcffa 0x1 0x0 0x0 0x0
+		       0x4 0x126 0xfcffb 0x1>;
+      #size-cells = <0x2>;
+      device-id = <0x4c1>;
+      phandle = <0x622>;
+      reg = <0x0 0x0 0x0 0x0 0x0>;
+    };
+  };
diff --git a/doc/pci.rst b/doc/pci.rst
index 5ccfd6e..f72fc14 100644
--- a/doc/pci.rst
+++ b/doc/pci.rst
@@ -59,3 +59,8 @@ To Manage DMA Windows :
 
 1. The host calls ``opal_pci_map_pe_dma_window( phb_id, dma_window_number, pe_number, tce_levels, tce_table_addr, tce_table_size, tce_page_size, utin64_t* pci_start_addr )`` to setup a DMA window for a PE to translate through a TCE table structure in KVM memory.
 2. The host calls ``opal_pci_map_pe_dma_window_real( phb_id, dma_window_number, pe_number, mem_low_addr, mem_high_addr)`` to setup a DMA window for a PE that is translated (but validated by the PHB as an untranlsated address space authorized to this PE).
+
+Device Tree Bindings
+--------------------
+
+See :doc:`device-tree/pci` for device tree information.