GNU Linux-libre 4.14.266-gnu1
[releases.git] / Documentation / devicetree / bindings / pci / ralink,rt3883-pci.txt
1 * Mediatek/Ralink RT3883 PCI controller
2
3 1) Main node
4
5    Required properties:
6
7    - compatible: must be "ralink,rt3883-pci"
8
9    - reg: specifies the physical base address of the controller and
10      the length of the memory mapped region.
11
12    - #address-cells: specifies the number of cells needed to encode an
13      address. The value must be 1.
14
15    - #size-cells: specifies the number of cells used to represent the size
16      of an address. The value must be 1.
17
18    - ranges: specifies the translation between child address space and parent
19      address space
20
21   Optional properties:
22
23    - status: indicates the operational status of the device.
24      Value must be either "disabled" or "okay".
25
26 2) Child nodes
27
28    The main node must have two child nodes which describes the built-in
29    interrupt controller and the PCI host bridge.
30
31    a) Interrupt controller:
32
33    Required properties:
34
35    - interrupt-controller: identifies the node as an interrupt controller
36
37    - #address-cells: specifies the number of cells needed to encode an
38      address. The value must be 0. As such, 'interrupt-map' nodes do not
39      have to specify a parent unit address.
40
41    - #interrupt-cells: specifies the number of cells needed to encode an
42      interrupt source. The value must be 1.
43
44    - interrupt-parent: the phandle for the interrupt controller that
45      services interrupts for this device.
46
47    - interrupts: specifies the interrupt source of the parent interrupt
48      controller. The format of the interrupt specifier depends on the
49      parent interrupt controller.
50
51    b) PCI host bridge:
52
53    Required properties:
54
55    - #address-cells: specifies the number of cells needed to encode an
56      address. The value must be 0.
57
58    - #size-cells: specifies the number of cells used to represent the size
59      of an address. The value must be 2.
60
61    - #interrupt-cells: specifies the number of cells needed to encode an
62      interrupt source. The value must be 1.
63
64    - device_type: must be "pci"
65
66    - bus-range: PCI bus numbers covered
67
68    - ranges: specifies the ranges for the PCI memory and I/O regions
69
70    - interrupt-map-mask,
71    - interrupt-map: standard PCI properties to define the mapping of the
72      PCI interface to interrupt numbers.
73
74    The PCI host bridge node might have additional sub-nodes representing
75    the onboard PCI devices/PCI slots. Each such sub-node must have the
76    following mandatory properties:
77
78      - reg: used only for interrupt mapping, so only the first four bytes
79        are used to refer to the correct bus number and device number.
80
81      - device_type: must be "pci"
82
83    If a given sub-node represents a PCI bridge it must have following
84    mandatory properties as well:
85
86      - #address-cells: must be set to <3>
87
88      - #size-cells: must set to <2>
89
90      - #interrupt-cells: must be set to <1>
91
92      - interrupt-map-mask,
93      - interrupt-map: standard PCI properties to define the mapping of the
94        PCI interface to interrupt numbers.
95
96    Besides the required properties the sub-nodes may have these optional
97    properties:
98
99      - status: indicates the operational status of the sub-node.
100        Value must be either "disabled" or "okay".
101
102 3) Example:
103
104    a) SoC specific dtsi file:
105
106         pci@10140000 {
107                 compatible = "ralink,rt3883-pci";
108                 reg = <0x10140000 0x20000>;
109                 #address-cells = <1>;
110                 #size-cells = <1>;
111                 ranges; /* direct mapping */
112
113                 status = "disabled";
114
115                 pciintc: interrupt-controller {
116                         interrupt-controller;
117                         #address-cells = <0>;
118                         #interrupt-cells = <1>;
119
120                         interrupt-parent = <&cpuintc>;
121                         interrupts = <4>;
122                 };
123
124                 host-bridge {
125                         #address-cells = <3>;
126                         #size-cells = <2>;
127                         #interrupt-cells = <1>;
128
129                         device_type = "pci";
130
131                         bus-range = <0 255>;
132                         ranges = <
133                                 0x02000000 0 0x00000000 0x20000000 0 0x10000000 /* pci memory */
134                                 0x01000000 0 0x00000000 0x10160000 0 0x00010000 /* io space */
135                         >;
136
137                         interrupt-map-mask = <0xf800 0 0 7>;
138                         interrupt-map = <
139                                 /* IDSEL 17 */
140                                 0x8800 0 0 1 &pciintc 18
141                                 0x8800 0 0 2 &pciintc 18
142                                 0x8800 0 0 3 &pciintc 18
143                                 0x8800 0 0 4 &pciintc 18
144                                 /* IDSEL 18 */
145                                 0x9000 0 0 1 &pciintc 19
146                                 0x9000 0 0 2 &pciintc 19
147                                 0x9000 0 0 3 &pciintc 19
148                                 0x9000 0 0 4 &pciintc 19
149                         >;
150
151                         pci-bridge@1 {
152                                 reg = <0x0800 0 0 0 0>;
153                                 device_type = "pci";
154                                 #interrupt-cells = <1>;
155                                 #address-cells = <3>;
156                                 #size-cells = <2>;
157
158                                 interrupt-map-mask = <0x0 0 0 0>;
159                                 interrupt-map = <0x0 0 0 0 &pciintc 20>;
160
161                                 status = "disabled";
162                         };
163
164                         pci-slot@17 {
165                                 reg = <0x8800 0 0 0 0>;
166                                 device_type = "pci";
167
168                                 status = "disabled";
169                         };
170
171                         pci-slot@18 {
172                                 reg = <0x9000 0 0 0 0>;
173                                 device_type = "pci";
174
175                                 status = "disabled";
176                         };
177                 };
178         };
179
180    b) Board specific dts file:
181
182         pci@10140000 {
183                 status = "okay";
184
185                 host-bridge {
186                         pci-bridge@1 {
187                                 status = "okay";
188                         };
189                 };
190         };