[U-Boot] [PATCH v3 4/4] dm: pci: Document binding of pci device drivers

[Bin Meng]

Document how pci devices are bound to device drivers.

Signed-off-by: Bin Meng <bmeng.cn at gmail.com>

---

Changes in v3: None

 doc/driver-model/pci-info.txt | 71 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 68 insertions(+), 3 deletions(-)

diff --git a/doc/driver-model/pci-info.txt b/doc/driver-model/pci-info.txt
index cf69167..52b4389 100644
--- a/doc/driver-model/pci-info.txt
+++ b/doc/driver-model/pci-info.txt
@@ -34,9 +34,74 @@ under that bus.
 Note that this is all done on a lazy basis, as needed, so until something is
 touched on PCI (eg: a call to pci_find_devices()) it will not be probed.
 
-PCI devices can appear in the device tree. If they do this serves to specify
-the driver to use for the device. In this case they will be bound at
-start-up.
+PCI devices can appear in the flattened device tree. If they do this serves to
+specify the driver to use for the device. In this case they will be bound at
+first. Each PCI device node must have a compatible string list as well as a
+<reg> property, as defined by the IEEE Std 1275-1994 PCI bus binding document
+v2.1. Note we must describe PCI devices with the same bus hierarchy as the
+hardware, otherwise driver model cannot detect the correct parent/children
+relationship during PCI bus enumeration thus PCI devices won't be bound to
+their drivers accordingly. A working example like below:
+
+	pci {
+		#address-cells = <3>;
+		#size-cells = <2>;
+		compatible = "pci-x86";
+		u-boot,dm-pre-reloc;
+		ranges = <0x02000000 0x0 0x40000000 0x40000000 0 0x80000000
+			  0x42000000 0x0 0xc0000000 0xc0000000 0 0x20000000
+			  0x01000000 0x0 0x2000 0x2000 0 0xe000>;
+
+		pcie at 17,0 {
+			#address-cells = <3>;
+			#size-cells = <2>;
+			compatible = "pci-bridge";
+			u-boot,dm-pre-reloc;
+			reg = <0x0000b800 0x0 0x0 0x0 0x0>;
+
+			topcliff at 0,0 {
+				#address-cells = <3>;
+				#size-cells = <2>;
+				compatible = "pci-bridge";
+				u-boot,dm-pre-reloc;
+				reg = <0x00010000 0x0 0x0 0x0 0x0>;
+
+				pciuart0: uart at a,1 {
+					compatible = "pci8086,8811.00",
+							"pci8086,8811",
+							"pciclass,070002",
+							"pciclass,0700",
+							"x86-uart";
+					u-boot,dm-pre-reloc;
+					reg = <0x00025100 0x0 0x0 0x0 0x0
+					       0x01025110 0x0 0x0 0x0 0x0>;
+					......
+				};
+
+				......
+			};
+		};
+
+		......
+	};
+
+In this example, the root PCI bus node is the "/pci" which matches "pci-x86"
+driver. It has a subnode "pcie at 17,0" with driver "pci-bridge". "pcie at 17,0"
+also has subnode "topcliff at 0,0" which is a "pci-bridge" too. Under that bridge,
+a PCI UART device "uart at a,1" is described. This exactly reflects the hardware
+bus hierarchy: on the root PCI bus, there is a PCIe root port which connects
+to a downstream device Topcliff chipset. Inside Topcliff chipset, it has a
+PCIe-to-PCI bridge and all the chipset integrated devices like the PCI UART
+device are on the PCI bus. Like other devices in the device tree, if we want
+to bind PCI devices before relocation, "u-boot,dm-pre-reloc" must be declared
+in each of these nodes.
+
+If PCI devices are not listed in the device tree, U_BOOT_PCI_DEVICE can be used
+to specify the driver to use for the device. The device tree takes precedence
+over U_BOOT_PCI_DEVICE. Plese note with U_BOOT_PCI_DEVICE, only drivers with
+DM_FLAG_PRE_RELOC will be bound before relocation. If neither device tree nor
+U_BOOT_PCI_DEVICE is provided, the built-in driver (either pci_bridge_drv or
+pci_generic_drv) will be used.
 
 
 Sandbox
-- 
1.8.2.1