GNU Linux-libre 4.14.266-gnu1
[releases.git] / Documentation / devicetree / bindings / net / keystone-netcp.txt
1 This document describes the device tree bindings associated with the
2 keystone network coprocessor(NetCP) driver support.
3
4 The network coprocessor (NetCP) is a hardware accelerator that processes
5 Ethernet packets. NetCP has a gigabit Ethernet (GbE) subsystem with a ethernet
6 switch sub-module to send and receive packets. NetCP also includes a packet
7 accelerator (PA) module to perform packet classification operations such as
8 header matching, and packet modification operations such as checksum
9 generation. NetCP can also optionally include a Security Accelerator (SA)
10 capable of performing IPSec operations on ingress/egress packets.
11
12 Keystone II SoC's also have a 10 Gigabit Ethernet Subsystem (XGbE) which
13 includes a 3-port Ethernet switch sub-module capable of 10Gb/s and 1Gb/s rates
14 per Ethernet port.
15
16 Keystone NetCP driver has a plug-in module architecture where each of the NetCP
17 sub-modules exist as a loadable kernel module which plug in to the netcp core.
18 These sub-modules are represented as "netcp-devices" in the dts bindings. It is
19 mandatory to have the ethernet switch sub-module for the ethernet interface to
20 be operational. Any other sub-module like the PA is optional.
21
22 NetCP Ethernet SubSystem Layout:
23
24 -----------------------------
25   NetCP subsystem(10G or 1G)
26 -----------------------------
27         |
28         |-> NetCP Devices ->    |
29         |                       |-> GBE/XGBE Switch
30         |                       |
31         |                       |-> Packet Accelerator
32         |                       |
33         |                       |-> Security Accelerator
34         |
35         |
36         |
37         |-> NetCP Interfaces -> |
38                                 |-> Ethernet Port 0
39                                 |
40                                 |-> Ethernet Port 1
41                                 |
42                                 |-> Ethernet Port 2
43                                 |
44                                 |-> Ethernet Port 3
45
46
47 NetCP subsystem properties:
48 Required properties:
49 - compatible:   Should be "ti,netcp-1.0"
50 - clocks:       phandle to the reference clocks for the subsystem.
51 - dma-id:       Navigator packet dma instance id.
52 - ranges:       address range of NetCP (includes, Ethernet SS, PA and SA)
53
54 Optional properties:
55 - reg:          register location and the size for the following register
56                 regions in the specified order.
57                 - Efuse MAC address register
58 - dma-coherent: Present if dma operations are coherent
59 - big-endian:   Keystone devices can be operated in a mode where the DSP is in
60                 the big endian mode. In such cases enable this option. This
61                 option should also be enabled if the ARM is operated in
62                 big endian mode with the DSP in little endian.
63
64 NetCP device properties: Device specification for NetCP sub-modules.
65 1Gb/10Gb (gbe/xgbe) ethernet switch sub-module specifications.
66 Required properties:
67 - label:        Must be "netcp-gbe" for 1Gb & "netcp-xgbe" for 10Gb.
68 - compatible:   Must be one of below:-
69                 "ti,netcp-gbe" for 1GbE on NetCP 1.4
70                 "ti,netcp-gbe-5" for 1GbE N NetCP 1.5 (N=5)
71                 "ti,netcp-gbe-9" for 1GbE N NetCP 1.5 (N=9)
72                 "ti,netcp-gbe-2" for 1GbE N NetCP 1.5 (N=2)
73                 "ti,netcp-xgbe" for 10 GbE
74
75 - reg:          register location and the size for the following register
76                 regions in the specified order.
77                 - switch subsystem registers
78                 - sgmii port3/4 module registers (only for NetCP 1.4)
79                 - switch module registers
80                 - serdes registers (only for 10G)
81
82                 NetCP 1.4 ethss, here is the order
83                         index #0 - switch subsystem registers
84                         index #1 - sgmii port3/4 module registers
85                         index #2 - switch module registers
86
87                 NetCP 1.5 ethss 9 port, 5 port and 2 port
88                         index #0 - switch subsystem registers
89                         index #1 - switch module registers
90                         index #2 - serdes registers
91
92 - tx-channel:   the navigator packet dma channel name for tx.
93 - tx-queue:     the navigator queue number associated with the tx dma channel.
94 - interfaces:   specification for each of the switch port to be registered as a
95                 network interface in the stack.
96 -- slave-port:  Switch port number, 0 based numbering.
97 -- link-interface:      type of link interface, supported options are
98                         - mac<->mac auto negotiate mode: 0
99                         - mac<->phy mode: 1
100                         - mac<->mac forced mode: 2
101                         - mac<->fiber mode: 3
102                         - mac<->phy mode with no mdio: 4
103                         - 10Gb mac<->phy mode : 10
104                         - 10Gb mac<->mac forced mode : 11
105 ----phy-handle: phandle to PHY device
106
107 Optional properties:
108 - enable-ale:   NetCP driver keeps the address learning feature in the ethernet
109                 switch module disabled. This attribute is to enable the address
110                 learning.
111 - secondary-slave-ports:        specification for each of the switch port not be
112                                 registered as a network interface. NetCP driver
113                                 will only initialize these ports and attach PHY
114                                 driver to them if needed.
115
116 NetCP interface properties: Interface specification for NetCP sub-modules.
117 Required properties:
118 - rx-channel:   the navigator packet dma channel name for rx.
119 - rx-queue:     the navigator queue number associated with rx dma channel.
120 - rx-pool:      specifies the number of descriptors to be used & the region-id
121                 for creating the rx descriptor pool.
122 - tx-pool:      specifies the number of descriptors to be used & the region-id
123                 for creating the tx descriptor pool.
124 - rx-queue-depth:       number of descriptors in each of the free descriptor
125                         queue (FDQ) for the pktdma Rx flow. There can be at
126                         present a maximum of 4 queues per Rx flow.
127 - rx-buffer-size:       the buffer size for each of the Rx flow FDQ.
128 - tx-completion-queue:  the navigator queue number where the descriptors are
129                         recycled after Tx DMA completion.
130
131 Optional properties:
132 - efuse-mac:    If this is 1, then the MAC address for the interface is
133                 obtained from the device efuse mac address register.
134                 If this is 2, the two DWORDs occupied by the MAC address
135                 are swapped.  The netcp driver will swap the two DWORDs
136                 back to the proper order when this property is set to 2
137                 when it obtains the mac address from efuse.
138 - local-mac-address:    the driver is designed to use the of_get_mac_address api
139                         only if efuse-mac is 0. When efuse-mac is 0, the MAC
140                         address is obtained from local-mac-address. If this
141                         attribute is not present, then the driver will use a
142                         random MAC address.
143 - "netcp-device label": phandle to the device specification for each of NetCP
144                         sub-module attached to this interface.
145
146 Example binding:
147
148 netcp: netcp@2000000 {
149         reg = <0x2620110 0x8>;
150         reg-names = "efuse";
151         compatible = "ti,netcp-1.0";
152         #address-cells = <1>;
153         #size-cells = <1>;
154         ranges  = <0 0x2000000 0xfffff>;
155         clocks = <&papllclk>, <&clkcpgmac>, <&chipclk12>;
156         dma-coherent;
157         /* big-endian; */
158         dma-id = <0>;
159
160         netcp-devices {
161                 #address-cells = <1>;
162                 #size-cells = <1>;
163                 ranges;
164                 gbe@90000 {
165                         label = "netcp-gbe";
166                         reg = <0x90000 0x300>, <0x90400 0x400>, <0x90800 0x700>;
167                         /* enable-ale; */
168                         tx-queue = <648>;
169                         tx-channel = <8>;
170
171                         interfaces {
172                                 gbe0: interface-0 {
173                                         slave-port = <0>;
174                                         link-interface  = <4>;
175                                 };
176                                 gbe1: interface-1 {
177                                         slave-port = <1>;
178                                         link-interface  = <4>;
179                                 };
180                         };
181
182                         secondary-slave-ports {
183                                 port-2 {
184                                         slave-port = <2>;
185                                         link-interface  = <2>;
186                                 };
187                                 port-3 {
188                                         slave-port = <3>;
189                                         link-interface  = <2>;
190                                 };
191                         };
192                 };
193         };
194
195         netcp-interfaces {
196                 interface-0 {
197                         rx-channel = <22>;
198                         rx-pool = <1024 12>;
199                         tx-pool = <1024 12>;
200                         rx-queue-depth = <128 128 0 0>;
201                         rx-buffer-size = <1518 4096 0 0>;
202                         rx-queue = <8704>;
203                         tx-completion-queue = <8706>;
204                         efuse-mac = <1>;
205                         netcp-gbe = <&gbe0>;
206
207                 };
208                 interface-1 {
209                         rx-channel = <23>;
210                         rx-pool = <1024 12>;
211                         tx-pool = <1024 12>;
212                         rx-queue-depth = <128 128 0 0>;
213                         rx-buffer-size = <1518 4096 0 0>;
214                         rx-queue = <8705>;
215                         tx-completion-queue = <8707>;
216                         efuse-mac = <0>;
217                         local-mac-address = [02 18 31 7e 3e 6f];
218                         netcp-gbe = <&gbe1>;
219                 };
220         };
221 };