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>

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>
Bin Meng · Simon Glass
1 parent a1f1582b73
Showing 1 changed file with 68 additions and 3 deletions Side-by-side Diff
doc/driver-model/pci-info.txt
@@ -34,9 +34,74 @@
 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
...	...	@@ -34,9 +34,74 @@
34	34	Note that this is all done on a lazy basis, as needed, so until something is
35	35	touched on PCI (eg: a call to pci_find_devices()) it will not be probed.
36	36
37		-PCI devices can appear in the device tree. If they do this serves to specify
38		-the driver to use for the device. In this case they will be bound at
39		-start-up.
	37	+PCI devices can appear in the flattened device tree. If they do this serves to
	38	+specify the driver to use for the device. In this case they will be bound at
	39	+first. Each PCI device node must have a compatible string list as well as a
	40	+<reg> property, as defined by the IEEE Std 1275-1994 PCI bus binding document
	41	+v2.1. Note we must describe PCI devices with the same bus hierarchy as the
	42	+hardware, otherwise driver model cannot detect the correct parent/children
	43	+relationship during PCI bus enumeration thus PCI devices won't be bound to
	44	+their drivers accordingly. A working example like below:
	45	+
	46	+ pci {
	47	+ #address-cells = <3>;
	48	+ #size-cells = <2>;
	49	+ compatible = "pci-x86";
	50	+ u-boot,dm-pre-reloc;
	51	+ ranges = <0x02000000 0x0 0x40000000 0x40000000 0 0x80000000
	52	+ 0x42000000 0x0 0xc0000000 0xc0000000 0 0x20000000
	53	+ 0x01000000 0x0 0x2000 0x2000 0 0xe000>;
	54	+
	55	+ pcie@17,0 {
	56	+ #address-cells = <3>;
	57	+ #size-cells = <2>;
	58	+ compatible = "pci-bridge";
	59	+ u-boot,dm-pre-reloc;
	60	+ reg = <0x0000b800 0x0 0x0 0x0 0x0>;
	61	+
	62	+ topcliff@0,0 {
	63	+ #address-cells = <3>;
	64	+ #size-cells = <2>;
	65	+ compatible = "pci-bridge";
	66	+ u-boot,dm-pre-reloc;
	67	+ reg = <0x00010000 0x0 0x0 0x0 0x0>;
	68	+
	69	+ pciuart0: uart@a,1 {
	70	+ compatible = "pci8086,8811.00",
	71	+ "pci8086,8811",
	72	+ "pciclass,070002",
	73	+ "pciclass,0700",
	74	+ "x86-uart";
	75	+ u-boot,dm-pre-reloc;
	76	+ reg = <0x00025100 0x0 0x0 0x0 0x0
	77	+ 0x01025110 0x0 0x0 0x0 0x0>;
	78	+ ......
	79	+ };
	80	+
	81	+ ......
	82	+ };
	83	+ };
	84	+
	85	+ ......
	86	+ };
	87	+
	88	+In this example, the root PCI bus node is the "/pci" which matches "pci-x86"
	89	+driver. It has a subnode "pcie@17,0" with driver "pci-bridge". "pcie@17,0"
	90	+also has subnode "topcliff@0,0" which is a "pci-bridge" too. Under that bridge,
	91	+a PCI UART device "uart@a,1" is described. This exactly reflects the hardware
	92	+bus hierarchy: on the root PCI bus, there is a PCIe root port which connects
	93	+to a downstream device Topcliff chipset. Inside Topcliff chipset, it has a
	94	+PCIe-to-PCI bridge and all the chipset integrated devices like the PCI UART
	95	+device are on the PCI bus. Like other devices in the device tree, if we want
	96	+to bind PCI devices before relocation, "u-boot,dm-pre-reloc" must be declared
	97	+in each of these nodes.
	98	+
	99	+If PCI devices are not listed in the device tree, U_BOOT_PCI_DEVICE can be used
	100	+to specify the driver to use for the device. The device tree takes precedence
	101	+over U_BOOT_PCI_DEVICE. Plese note with U_BOOT_PCI_DEVICE, only drivers with
	102	+DM_FLAG_PRE_RELOC will be bound before relocation. If neither device tree nor
	103	+U_BOOT_PCI_DEVICE is provided, the built-in driver (either pci_bridge_drv or
	104	+pci_generic_drv) will be used.
40	105
41	106
42	107	Sandbox