linux-zen-server/Documentation/devicetree/bindings/pci/ralink,rt3883-pci.txt

* Mediatek/Ralink RT3883 PCI controller

1) Main node

   Required properties:

   - compatible: must be "ralink,rt3883-pci"

   - reg: specifies the physical base address of the controller and
     the length of the memory mapped region.

   - #address-cells: specifies the number of cells needed to encode an
     address. The value must be 1.

   - #size-cells: specifies the number of cells used to represent the size
     of an address. The value must be 1.

   - ranges: specifies the translation between child address space and parent
     address space

  Optional properties:

   - status: indicates the operational status of the device.
     Value must be either "disabled" or "okay".

2) Child nodes

   The main node must have two child nodes which describes the built-in
   interrupt controller and the PCI host bridge.

   a) Interrupt controller:

   Required properties:

   - interrupt-controller: identifies the node as an interrupt controller

   - #address-cells: specifies the number of cells needed to encode an
     address. The value must be 0. As such, 'interrupt-map' nodes do not
     have to specify a parent unit address.

   - #interrupt-cells: specifies the number of cells needed to encode an
     interrupt source. The value must be 1.

   - interrupts: specifies the interrupt source of the parent interrupt
     controller. The format of the interrupt specifier depends on the
     parent interrupt controller.

   b) PCI host bridge:

   Required properties:

   - #address-cells: specifies the number of cells needed to encode an
     address. The value must be 0.

   - #size-cells: specifies the number of cells used to represent the size
     of an address. The value must be 2.

   - #interrupt-cells: specifies the number of cells needed to encode an
     interrupt source. The value must be 1.

   - device_type: must be "pci"

   - bus-range: PCI bus numbers covered

   - ranges: specifies the ranges for the PCI memory and I/O regions

   - interrupt-map-mask,
   - interrupt-map: standard PCI properties to define the mapping of the
     PCI interface to interrupt numbers.

   The PCI host bridge node might have additional sub-nodes representing
   the onboard PCI devices/PCI slots. Each such sub-node must have the
   following mandatory properties:

     - reg: used only for interrupt mapping, so only the first four bytes
       are used to refer to the correct bus number and device number.

     - device_type: must be "pci"

   If a given sub-node represents a PCI bridge it must have following
   mandatory properties as well:

     - #address-cells: must be set to <3>

     - #size-cells: must set to <2>

     - #interrupt-cells: must be set to <1>

     - interrupt-map-mask,
     - interrupt-map: standard PCI properties to define the mapping of the
       PCI interface to interrupt numbers.

   Besides the required properties the sub-nodes may have these optional
   properties:

     - status: indicates the operational status of the sub-node.
       Value must be either "disabled" or "okay".

3) Example:

   a) SoC specific dtsi file:

	pci@10140000 {
		compatible = "ralink,rt3883-pci";
		reg = <0x10140000 0x20000>;
		#address-cells = <1>;
		#size-cells = <1>;
		ranges; /* direct mapping */

		status = "disabled";

		pciintc: interrupt-controller {
			interrupt-controller;
			#address-cells = <0>;
			#interrupt-cells = <1>;

			interrupt-parent = <&cpuintc>;
			interrupts = <4>;
		};

		host-bridge {
			#address-cells = <3>;
			#size-cells = <2>;
			#interrupt-cells = <1>;

			device_type = "pci";

			bus-range = <0 255>;
			ranges = <
				0x02000000 0 0x00000000 0x20000000 0 0x10000000 /* pci memory */
				0x01000000 0 0x00000000 0x10160000 0 0x00010000 /* io space */
			>;

			interrupt-map-mask = <0xf800 0 0 7>;
			interrupt-map = <
				/* IDSEL 17 */
				0x8800 0 0 1 &pciintc 18
				0x8800 0 0 2 &pciintc 18
				0x8800 0 0 3 &pciintc 18
				0x8800 0 0 4 &pciintc 18
				/* IDSEL 18 */
				0x9000 0 0 1 &pciintc 19
				0x9000 0 0 2 &pciintc 19
				0x9000 0 0 3 &pciintc 19
				0x9000 0 0 4 &pciintc 19
			>;

			pci-bridge@1 {
				reg = <0x0800 0 0 0 0>;
				device_type = "pci";
				#interrupt-cells = <1>;
				#address-cells = <3>;
				#size-cells = <2>;

				interrupt-map-mask = <0x0 0 0 0>;
				interrupt-map = <0x0 0 0 0 &pciintc 20>;

				status = "disabled";
			};

			pci-slot@17 {
				reg = <0x8800 0 0 0 0>;
				device_type = "pci";

				status = "disabled";
			};

			pci-slot@18 {
				reg = <0x9000 0 0 0 0>;
				device_type = "pci";

				status = "disabled";
			};
		};
	};

   b) Board specific dts file:

	pci@10140000 {
		status = "okay";

		host-bridge {
			pci-bridge@1 {
				status = "okay";
			};
		};
	};