dm: pci: Document binding of pci device drivers

Document how pci devices are bound to device drivers.

Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
Acked-by: Simon Glass <sjg@chromium.org>

diff --git a/doc/driver-model/pci-info.txt b/doc/driver-model/pci-info.txt
index cf69167bd171b0b6203642ef7c3530f06fae79a5..52b4389d2cc86286fe00c4a5f90d7341ef49734a 100644 (file)
--- 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@17,0 {
+                       #address-cells = <3>;
+                       #size-cells = <2>;
+                       compatible = "pci-bridge";
+                       u-boot,dm-pre-reloc;
+                       reg = <0x0000b800 0x0 0x0 0x0 0x0>;
+
+                       topcliff@0,0 {
+                               #address-cells = <3>;
+                               #size-cells = <2>;
+                               compatible = "pci-bridge";
+                               u-boot,dm-pre-reloc;
+                               reg = <0x00010000 0x0 0x0 0x0 0x0>;
+
+                               pciuart0: uart@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@17,0" with driver "pci-bridge". "pcie@17,0"
+also has subnode "topcliff@0,0" which is a "pci-bridge" too. Under that bridge,
+a PCI UART device "uart@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