3ceeb8de11963572cc1bd8ce324433e0dbf6bd03
[sfrench/cifs-2.6.git] / Documentation / devicetree / bindings / net / dsa / dsa.txt
1 Distributed Switch Architecture Device Tree Bindings
2 ----------------------------------------------------
3
4 Two bindings exist, one of which has been deprecated due to
5 limitations.
6
7 Current Binding
8 ---------------
9
10 Switches are true Linux devices and can be probes by any means. Once
11 probed, they register to the DSA framework, passing a node
12 pointer. This node is expected to fulfil the following binding, and
13 may contain additional properties as required by the device it is
14 embedded within.
15
16 Required properties:
17
18 - ports         : A container for child nodes representing switch ports.
19
20 Optional properties:
21
22 - dsa,member    : A two element list indicates which DSA cluster, and position
23                   within the cluster a switch takes. <0 0> is cluster 0,
24                   switch 0. <0 1> is cluster 0, switch 1. <1 0> is cluster 1,
25                   switch 0. A switch not part of any cluster (single device
26                   hanging off a CPU port) must not specify this property
27
28 The ports container has the following properties
29
30 Required properties:
31
32 - #address-cells        : Must be 1
33 - #size-cells           : Must be 0
34
35 Each port children node must have the following mandatory properties:
36 - reg                   : Describes the port address in the switch
37
38 An uplink/downlink port between switches in the cluster has the following
39 mandatory property:
40
41 - link                  : Should be a list of phandles to other switch's DSA
42                           port. This port is used as the outgoing port
43                           towards the phandle ports. The full routing
44                           information must be given, not just the one hop
45                           routes to neighbouring switches.
46
47 A CPU port has the following mandatory property:
48
49 - ethernet              : Should be a phandle to a valid Ethernet device node.
50                           This host device is what the switch port is
51                           connected to.
52
53 A user port has the following optional property:
54
55 - label                 : Describes the label associated with this port, which
56                           will become the netdev name.
57
58 Port child nodes may also contain the following optional standardised
59 properties, described in binding documents:
60
61 - phy-handle            : Phandle to a PHY on an MDIO bus. See
62                           Documentation/devicetree/bindings/net/ethernet.txt
63                           for details.
64
65 - phy-mode              : See
66                           Documentation/devicetree/bindings/net/ethernet.txt
67                           for details.
68
69 - fixed-link            : Fixed-link subnode describing a link to a non-MDIO
70                           managed entity. See
71                           Documentation/devicetree/bindings/net/fixed-link.txt
72                           for details.
73
74 Example
75
76 The following example shows three switches on three MDIO busses,
77 linked into one DSA cluster.
78
79 &mdio1 {
80         #address-cells = <1>;
81         #size-cells = <0>;
82
83         switch0: switch0@0 {
84                 compatible = "marvell,mv88e6085";
85                 reg = <0>;
86
87                 dsa,member = <0 0>;
88
89                 ports {
90                         #address-cells = <1>;
91                         #size-cells = <0>;
92                         port@0 {
93                                 reg = <0>;
94                                 label = "lan0";
95                         };
96
97                         port@1 {
98                                 reg = <1>;
99                                 label = "lan1";
100                         };
101
102                         port@2 {
103                                 reg = <2>;
104                                 label = "lan2";
105                         };
106
107                         switch0port5: port@5 {
108                                 reg = <5>;
109                                 phy-mode = "rgmii-txid";
110                                 link = <&switch1port6
111                                         &switch2port9>;
112                                 fixed-link {
113                                         speed = <1000>;
114                                         full-duplex;
115                                 };
116                         };
117
118                         port@6 {
119                                 reg = <6>;
120                                 ethernet = <&fec1>;
121                                 fixed-link {
122                                         speed = <100>;
123                                         full-duplex;
124                                 };
125                         };
126                 };
127         };
128 };
129
130 &mdio2 {
131         #address-cells = <1>;
132         #size-cells = <0>;
133
134         switch1: switch1@0 {
135                 compatible = "marvell,mv88e6085";
136                 reg = <0>;
137
138                 dsa,member = <0 1>;
139
140                 ports {
141                         #address-cells = <1>;
142                         #size-cells = <0>;
143                         port@0 {
144                                 reg = <0>;
145                                 label = "lan3";
146                                 phy-handle = <&switch1phy0>;
147                         };
148
149                         port@1 {
150                                 reg = <1>;
151                                 label = "lan4";
152                                 phy-handle = <&switch1phy1>;
153                         };
154
155                         port@2 {
156                                 reg = <2>;
157                                 label = "lan5";
158                                 phy-handle = <&switch1phy2>;
159                         };
160
161                         switch1port5: port@5 {
162                                 reg = <5>;
163                                 link = <&switch2port9>;
164                                 phy-mode = "rgmii-txid";
165                                 fixed-link {
166                                         speed = <1000>;
167                                         full-duplex;
168                                 };
169                         };
170
171                         switch1port6: port@6 {
172                                 reg = <6>;
173                                 phy-mode = "rgmii-txid";
174                                 link = <&switch0port5>;
175                                 fixed-link {
176                                         speed = <1000>;
177                                         full-duplex;
178                                 };
179                         };
180                 };
181                 mdio-bus {
182                         #address-cells = <1>;
183                         #size-cells = <0>;
184                         switch1phy0: switch1phy0@0 {
185                                 reg = <0>;
186                         };
187                         switch1phy1: switch1phy0@1 {
188                                 reg = <1>;
189                         };
190                         switch1phy2: switch1phy0@2 {
191                                 reg = <2>;
192                         };
193                 };
194          };
195 };
196
197 &mdio4 {
198         #address-cells = <1>;
199         #size-cells = <0>;
200
201         switch2: switch2@0 {
202                 compatible = "marvell,mv88e6085";
203                 reg = <0>;
204
205                 dsa,member = <0 2>;
206
207                 ports {
208                         #address-cells = <1>;
209                         #size-cells = <0>;
210                         port@0 {
211                                 reg = <0>;
212                                 label = "lan6";
213                         };
214
215                         port@1 {
216                                 reg = <1>;
217                                 label = "lan7";
218                         };
219
220                         port@2 {
221                                 reg = <2>;
222                                 label = "lan8";
223                         };
224
225                         port@3 {
226                                 reg = <3>;
227                                 label = "optical3";
228                                 fixed-link {
229                                         speed = <1000>;
230                                         full-duplex;
231                                         link-gpios = <&gpio6 2
232                                               GPIO_ACTIVE_HIGH>;
233                                 };
234                         };
235
236                         port@4 {
237                                 reg = <4>;
238                                 label = "optical4";
239                                 fixed-link {
240                                         speed = <1000>;
241                                         full-duplex;
242                                         link-gpios = <&gpio6 3
243                                               GPIO_ACTIVE_HIGH>;
244                                 };
245                         };
246
247                         switch2port9: port@9 {
248                                 reg = <9>;
249                                 phy-mode = "rgmii-txid";
250                                 link = <&switch1port5
251                                         &switch0port5>;
252                                 fixed-link {
253                                         speed = <1000>;
254                                         full-duplex;
255                                 };
256                         };
257                 };
258         };
259 };
260
261 Deprecated Binding
262 ------------------
263
264 The deprecated binding makes use of a platform device to represent the
265 switches. The switches themselves are not Linux devices, and make use
266 of an MDIO bus for management.
267
268 Required properties:
269 - compatible            : Should be "marvell,dsa"
270 - #address-cells        : Must be 2, first cell is the address on the MDIO bus
271                           and second cell is the address in the switch tree.
272                           Second cell is used only when cascading/chaining.
273 - #size-cells           : Must be 0
274 - dsa,ethernet          : Should be a phandle to a valid Ethernet device node
275 - dsa,mii-bus           : Should be a phandle to a valid MDIO bus device node
276
277 Optional properties:
278 - interrupts            : property with a value describing the switch
279                           interrupt number (not supported by the driver)
280
281 A DSA node can contain multiple switch chips which are therefore child nodes of
282 the parent DSA node. The maximum number of allowed child nodes is 4
283 (DSA_MAX_SWITCHES).
284 Each of these switch child nodes should have the following required properties:
285
286 - reg                   : Contains two fields. The first one describes the
287                           address on the MII bus. The second is the switch
288                           number that must be unique in cascaded configurations
289 - #address-cells        : Must be 1
290 - #size-cells           : Must be 0
291
292 A switch child node has the following optional property:
293
294 - eeprom-length         : Set to the length of an EEPROM connected to the
295                           switch. Must be set if the switch can not detect
296                           the presence and/or size of a connected EEPROM,
297                           otherwise optional.
298
299 A switch may have multiple "port" children nodes
300
301 Each port children node must have the following mandatory properties:
302 - reg                   : Describes the port address in the switch
303 - label                 : Describes the label associated with this port, special
304                           labels are "cpu" to indicate a CPU port and "dsa" to
305                           indicate an uplink/downlink port.
306
307 Note that a port labelled "dsa" will imply checking for the uplink phandle
308 described below.
309
310 Optional property:
311 - link                  : Should be a list of phandles to another switch's DSA port.
312                           This property is only used when switches are being
313                           chained/cascaded together. This port is used as outgoing port
314                           towards the phandle port, which can be more than one hop away.
315
316 - phy-handle            : Phandle to a PHY on an external MDIO bus, not the
317                           switch internal one. See
318                           Documentation/devicetree/bindings/net/ethernet.txt
319                           for details.
320
321 - phy-mode              : String representing the connection to the designated
322                           PHY node specified by the 'phy-handle' property. See
323                           Documentation/devicetree/bindings/net/ethernet.txt
324                           for details.
325
326 - mii-bus               : Should be a phandle to a valid MDIO bus device node.
327                           This mii-bus will be used in preference to the
328                           global dsa,mii-bus defined above, for this switch.
329
330 Optional subnodes:
331 - fixed-link            : Fixed-link subnode describing a link to a non-MDIO
332                           managed entity. See
333                           Documentation/devicetree/bindings/net/fixed-link.txt
334                           for details.
335
336 Example:
337
338         dsa@0 {
339                 compatible = "marvell,dsa";
340                 #address-cells = <2>;
341                 #size-cells = <0>;
342
343                 interrupts = <10>;
344                 dsa,ethernet = <&ethernet0>;
345                 dsa,mii-bus = <&mii_bus0>;
346
347                 switch@0 {
348                         #address-cells = <1>;
349                         #size-cells = <0>;
350                         reg = <16 0>;   /* MDIO address 16, switch 0 in tree */
351
352                         port@0 {
353                                 reg = <0>;
354                                 label = "lan1";
355                                 phy-handle = <&phy0>;
356                         };
357
358                         port@1 {
359                                 reg = <1>;
360                                 label = "lan2";
361                         };
362
363                         port@5 {
364                                 reg = <5>;
365                                 label = "cpu";
366                         };
367
368                         switch0port6: port@6 {
369                                 reg = <6>;
370                                 label = "dsa";
371                                 link = <&switch1port0
372                                         &switch2port0>;
373                         };
374                 };
375
376                 switch@1 {
377                         #address-cells = <1>;
378                         #size-cells = <0>;
379                         reg = <17 1>;   /* MDIO address 17, switch 1 in tree */
380                         mii-bus = <&mii_bus1>;
381                         reset-gpios = <&gpio5 1 GPIO_ACTIVE_LOW>;
382
383                         switch1port0: port@0 {
384                                 reg = <0>;
385                                 label = "dsa";
386                                 link = <&switch0port6>;
387                         };
388                         switch1port1: port@1 {
389                                 reg = <1>;
390                                 label = "dsa";
391                                 link = <&switch2port1>;
392                         };
393                 };
394
395                 switch@2 {
396                         #address-cells = <1>;
397                         #size-cells = <0>;
398                         reg = <18 2>;   /* MDIO address 18, switch 2 in tree */
399                         mii-bus = <&mii_bus1>;
400
401                         switch2port0: port@0 {
402                                 reg = <0>;
403                                 label = "dsa";
404                                 link = <&switch1port1
405                                         &switch0port6>;
406                         };
407                 };
408         };