]>
Commit | Line | Data |
---|---|---|
a1d6f3f6 GC |
1 | STMicroelectronics 10/100/1000 Synopsys Ethernet driver |
2 | ||
0b7a43d3 | 3 | Copyright (C) 2007-2015 STMicroelectronics Ltd |
a1d6f3f6 GC |
4 | Author: Giuseppe Cavallaro <peppe.cavallaro@st.com> |
5 | ||
6 | This is the driver for the MAC 10/100/1000 on-chip Ethernet controllers | |
5b993268 | 7 | (Synopsys IP blocks). |
a1d6f3f6 | 8 | |
233b36cf | 9 | Currently this network device driver is for all STi embedded MAC/GMAC |
5b993268 GC |
10 | (i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XLINX XC2V3000 |
11 | FF1152AMT0221 D1215994A VIRTEX FPGA board. | |
a1d6f3f6 | 12 | |
49cfbf67 | 13 | DWC Ether MAC 10/100/1000 Universal version 3.70a (and older) and DWC Ether |
3d237714 | 14 | MAC 10/100 Universal version 4.0 have been used for developing this driver. |
5b993268 GC |
15 | |
16 | This driver supports both the platform bus and PCI. | |
a1d6f3f6 GC |
17 | |
18 | Please, for more information also visit: www.stlinux.com | |
19 | ||
20 | 1) Kernel Configuration | |
21 | The kernel configuration option is STMMAC_ETH: | |
22 | Device Drivers ---> Network device support ---> Ethernet (1000 Mbit) ---> | |
23 | STMicroelectronics 10/100/1000 Ethernet driver (STMMAC_ETH) | |
24 | ||
233b36cf GC |
25 | CONFIG_STMMAC_PLATFORM: is to enable the platform driver. |
26 | CONFIG_STMMAC_PCI: is to enable the pci driver. | |
27 | ||
a1d6f3f6 GC |
28 | 2) Driver parameters list: |
29 | debug: message level (0: no output, 16: all); | |
30 | phyaddr: to manually provide the physical address to the PHY device; | |
a1d6f3f6 GC |
31 | buf_sz: DMA buffer size; |
32 | tc: control the HW FIFO threshold; | |
a1d6f3f6 GC |
33 | watchdog: transmit timeout (in milliseconds); |
34 | flow_ctrl: Flow control ability [on/off]; | |
35 | pause: Flow Control Pause Time; | |
49cfbf67 GC |
36 | eee_timer: tx EEE timer; |
37 | chain_mode: select chain mode instead of ring. | |
a1d6f3f6 GC |
38 | |
39 | 3) Command line options | |
40 | Driver parameters can be also passed in command line by using: | |
c6c60dae | 41 | stmmaceth=watchdog:100,chain_mode=1 |
a1d6f3f6 GC |
42 | |
43 | 4) Driver information and notes | |
44 | ||
45 | 4.1) Transmit process | |
46 | The xmit method is invoked when the kernel needs to transmit a packet; it sets | |
c6c60dae | 47 | the descriptors in the ring and informs the DMA engine, that there is a packet |
a1d6f3f6 | 48 | ready to be transmitted. |
a1d6f3f6 | 49 | By default, the driver sets the NETIF_F_SG bit in the features field of the |
c6c60dae | 50 | net_device structure, enabling the scatter-gather feature. This is true on |
233b36cf | 51 | chips and configurations where the checksum can be done in hardware. |
c6c60dae | 52 | Once the controller has finished transmitting the packet, timer will be |
233b36cf | 53 | scheduled to release the transmit resources. |
a1d6f3f6 GC |
54 | |
55 | 4.2) Receive process | |
56 | When one or more packets are received, an interrupt happens. The interrupts | |
c6c60dae | 57 | are not queued, so the driver has to scan all the descriptors in the ring during |
a1d6f3f6 | 58 | the receive process. |
c6c60dae | 59 | This is based on NAPI, so the interrupt handler signals only if there is work |
3d237714 | 60 | to be done, and it exits. |
a1d6f3f6 GC |
61 | Then the poll method will be scheduled at some future point. |
62 | The incoming packets are stored, by the DMA, in a list of pre-allocated socket | |
233b36cf | 63 | buffers in order to avoid the memcpy (zero-copy). |
a1d6f3f6 | 64 | |
c6c60dae | 65 | 4.3) Interrupt mitigation |
f9e01b55 GC |
66 | The driver is able to mitigate the number of its DMA interrupts |
67 | using NAPI for the reception on chips older than the 3.50. | |
68 | New chips have an HW RX-Watchdog used for this mitigation. | |
f9e01b55 | 69 | Mitigation parameters can be tuned by ethtool. |
a1d6f3f6 GC |
70 | |
71 | 4.4) WOL | |
3d237714 GC |
72 | Wake up on Lan feature through Magic and Unicast frames are supported for the |
73 | GMAC core. | |
a1d6f3f6 GC |
74 | |
75 | 4.5) DMA descriptors | |
233b36cf | 76 | Driver handles both normal and alternate descriptors. The latter has been only |
51e3137b GC |
77 | tested on DWC Ether MAC 10/100/1000 Universal version 3.41a and later. |
78 | ||
79 | STMMAC supports DMA descriptor to operate both in dual buffer (RING) | |
80 | and linked-list(CHAINED) mode. In RING each descriptor points to two | |
81 | data buffer pointers whereas in CHAINED mode they point to only one data | |
82 | buffer pointer. RING mode is the default. | |
83 | ||
84 | In CHAINED mode each descriptor will have pointer to next descriptor in | |
85 | the list, hence creating the explicit chaining in the descriptor itself, | |
86 | whereas such explicit chaining is not possible in RING mode. | |
a1d6f3f6 | 87 | |
233b36cf | 88 | 4.5.1) Extended descriptors |
c6c60dae PM |
89 | The extended descriptors give us information about the Ethernet payload |
90 | when it is carrying PTP packets or TCP/UDP/ICMP over IP. | |
91 | These are not available on GMAC Synopsys chips older than the 3.50. | |
92 | At probe time the driver will decide if these can be actually used. | |
93 | This support also is mandatory for PTPv2 because the extra descriptors | |
94 | are used for saving the hardware timestamps and Extended Status. | |
233b36cf | 95 | |
a1d6f3f6 | 96 | 4.6) Ethtool support |
233b36cf GC |
97 | Ethtool is supported. |
98 | ||
99 | For example, driver statistics (including RMON), internal errors can be taken | |
100 | using: | |
c6c60dae PM |
101 | # ethtool -S ethX |
102 | command | |
a1d6f3f6 GC |
103 | |
104 | 4.7) Jumbo and Segmentation Offloading | |
105 | Jumbo frames are supported and tested for the GMAC. | |
106 | The GSO has been also added but it's performed in software. | |
107 | LRO is not supported. | |
108 | ||
109 | 4.8) Physical | |
233b36cf GC |
110 | The driver is compatible with Physical Abstraction Layer to be connected with |
111 | PHY and GPHY devices. | |
a1d6f3f6 GC |
112 | |
113 | 4.9) Platform information | |
233b36cf | 114 | Several information can be passed through the platform and device-tree. |
a1d6f3f6 | 115 | |
3d237714 GC |
116 | struct plat_stmmacenet_data { |
117 | char *phy_bus_name; | |
f5539b5b | 118 | int bus_id; |
557e2a39 GC |
119 | int phy_addr; |
120 | int interface; | |
121 | struct stmmac_mdio_bus_data *mdio_bus_data; | |
8327eb65 | 122 | struct stmmac_dma_cfg *dma_cfg; |
f5539b5b GC |
123 | int clk_csr; |
124 | int has_gmac; | |
125 | int enh_desc; | |
126 | int tx_coe; | |
55f9a4d6 | 127 | int rx_coe; |
f5539b5b GC |
128 | int bugged_jumbo; |
129 | int pmt; | |
557e2a39 | 130 | int force_sf_dma_mode; |
e2a240c7 | 131 | int force_thresh_dma_mode; |
f9e01b55 | 132 | int riwt_off; |
233b36cf GC |
133 | int max_speed; |
134 | int maxmtu; | |
557e2a39 GC |
135 | void (*fix_mac_speed)(void *priv, unsigned int speed); |
136 | void (*bus_setup)(void __iomem *ioaddr); | |
938dfdaa CYT |
137 | int (*init)(struct platform_device *pdev, void *priv); |
138 | void (*exit)(struct platform_device *pdev, void *priv); | |
557e2a39 | 139 | void *bsp_priv; |
0b7a43d3 AT |
140 | int has_gmac4; |
141 | bool tso_en; | |
233b36cf | 142 | }; |
a1d6f3f6 GC |
143 | |
144 | Where: | |
3d237714 | 145 | o phy_bus_name: phy bus name to attach to the stmmac. |
557e2a39 GC |
146 | o bus_id: bus identifier. |
147 | o phy_addr: the physical address can be passed from the platform. | |
148 | If it is set to -1 the driver will automatically | |
149 | detect it at run-time by probing all the 32 addresses. | |
150 | o interface: PHY device's interface. | |
151 | o mdio_bus_data: specific platform fields for the MDIO bus. | |
3d237714 GC |
152 | o dma_cfg: internal DMA parameters |
153 | o pbl: the Programmable Burst Length is maximum number of beats to | |
557e2a39 | 154 | be transferred in one DMA transaction. |
4022d039 | 155 | GMAC also enables the 4xPBL by default. (8xPBL for GMAC 3.50 and newer) |
89caaa2d | 156 | o txpbl/rxpbl: GMAC and newer supports independent DMA pbl for tx/rx. |
4022d039 | 157 | o pblx8: Enable 8xPBL (4xPBL for core rev < 3.50). Enabled by default. |
89caaa2d | 158 | o fixed_burst/mixed_burst/aal |
cd7201f4 | 159 | o clk_csr: fixed CSR Clock range selection. |
557e2a39 GC |
160 | o has_gmac: uses the GMAC core. |
161 | o enh_desc: if sets the MAC will use the enhanced descriptor structure. | |
162 | o tx_coe: core is able to perform the tx csum in HW. | |
55f9a4d6 DS |
163 | o rx_coe: the supports three check sum offloading engine types: |
164 | type_1, type_2 (full csum) and no RX coe. | |
557e2a39 GC |
165 | o bugged_jumbo: some HWs are not able to perform the csum in HW for |
166 | over-sized frames due to limited buffer sizes. | |
167 | Setting this flag the csum will be done in SW on | |
168 | JUMBO frames. | |
169 | o pmt: core has the embedded power module (optional). | |
170 | o force_sf_dma_mode: force DMA to use the Store and Forward mode | |
171 | instead of the Threshold. | |
c17cb8b5 | 172 | o force_thresh_dma_mode: force DMA to use the Threshold mode other than |
e2a240c7 | 173 | the Store and Forward mode. |
f9e01b55 | 174 | o riwt_off: force to disable the RX watchdog feature and switch to NAPI mode. |
557e2a39 GC |
175 | o fix_mac_speed: this callback is used for modifying some syscfg registers |
176 | (on ST SoCs) according to the link speed negotiated by the | |
177 | physical layer . | |
178 | o bus_setup: perform HW setup of the bus. For example, on some ST platforms | |
179 | this field is used to configure the AMBA bridge to generate more | |
180 | efficient STBus traffic. | |
75fee595 | 181 | o init/exit: callbacks used for calling a custom initialization; |
557e2a39 GC |
182 | this is sometime necessary on some platforms (e.g. ST boxes) |
183 | where the HW needs to have set some PIO lines or system cfg | |
75fee595 | 184 | registers. init/exit callbacks should not use or modify |
938dfdaa | 185 | platform data. |
c17cb8b5 | 186 | o bsp_priv: another private pointer. |
0b7a43d3 AT |
187 | o has_gmac4: uses GMAC4 core. |
188 | o tso_en: Enables TSO (TCP Segmentation Offload) feature. | |
557e2a39 | 189 | |
8327eb65 | 190 | For MDIO bus The we have: |
557e2a39 GC |
191 | |
192 | struct stmmac_mdio_bus_data { | |
557e2a39 GC |
193 | int (*phy_reset)(void *priv); |
194 | unsigned int phy_mask; | |
195 | int *irqs; | |
196 | int probed_phy_irq; | |
197 | }; | |
a1d6f3f6 GC |
198 | |
199 | Where: | |
557e2a39 GC |
200 | o phy_reset: hook to reset the phy device attached to the bus. |
201 | o phy_mask: phy mask passed when register the MDIO bus within the driver. | |
202 | o irqs: list of IRQs, one per PHY. | |
203 | o probed_phy_irq: if irqs is NULL, use this for probed PHY. | |
204 | ||
8327eb65 DS |
205 | For DMA engine we have the following internal fields that should be |
206 | tuned according to the HW capabilities. | |
207 | ||
208 | struct stmmac_dma_cfg { | |
209 | int pbl; | |
89caaa2d NC |
210 | int txpbl; |
211 | int rxpbl; | |
4022d039 | 212 | bool pblx8; |
8327eb65 | 213 | int fixed_burst; |
89caaa2d NC |
214 | int mixed_burst; |
215 | bool aal; | |
8327eb65 DS |
216 | }; |
217 | ||
218 | Where: | |
89caaa2d NC |
219 | o pbl: Programmable Burst Length (tx and rx) |
220 | o txpbl: Transmit Programmable Burst Length. Only for GMAC and newer. | |
221 | If set, DMA tx will use this value rather than pbl. | |
222 | o rxpbl: Receive Programmable Burst Length. Only for GMAC and newer. | |
223 | If set, DMA rx will use this value rather than pbl. | |
4022d039 | 224 | o pblx8: Enable 8xPBL (4xPBL for core rev < 3.50). Enabled by default. |
8327eb65 | 225 | o fixed_burst: program the DMA to use the fixed burst mode |
89caaa2d NC |
226 | o mixed_burst: program the DMA to use the mixed burst mode |
227 | o aal: Address-Aligned Beats | |
8327eb65 DS |
228 | |
229 | --- | |
230 | ||
557e2a39 GC |
231 | Below an example how the structures above are using on ST platforms. |
232 | ||
233 | static struct plat_stmmacenet_data stxYYY_ethernet_platform_data = { | |
557e2a39 GC |
234 | .has_gmac = 0, |
235 | .enh_desc = 0, | |
236 | .fix_mac_speed = stxYYY_ethernet_fix_mac_speed, | |
237 | | | |
238 | |-> to write an internal syscfg | |
239 | | on this platform when the | |
240 | | link speed changes from 10 to | |
241 | | 100 and viceversa | |
242 | .init = &stmmac_claim_resource, | |
243 | | | |
244 | |-> On ST SoC this calls own "PAD" | |
245 | | manager framework to claim | |
246 | | all the resources necessary | |
247 | | (GPIO ...). The .custom_cfg field | |
248 | | is used to pass a custom config. | |
249 | }; | |
250 | ||
251 | Below the usage of the stmmac_mdio_bus_data: on this SoC, in fact, | |
252 | there are two MAC cores: one MAC is for MDIO Bus/PHY emulation | |
253 | with fixed_link support. | |
254 | ||
255 | static struct stmmac_mdio_bus_data stmmac1_mdio_bus = { | |
557e2a39 GC |
256 | .phy_reset = phy_reset; |
257 | | | |
258 | |-> function to provide the phy_reset on this board | |
259 | .phy_mask = 0, | |
260 | }; | |
261 | ||
262 | static struct fixed_phy_status stmmac0_fixed_phy_status = { | |
263 | .link = 1, | |
264 | .speed = 100, | |
265 | .duplex = 1, | |
266 | }; | |
267 | ||
268 | During the board's device_init we can configure the first | |
269 | MAC for fixed_link by calling: | |
a5597008 | 270 | fixed_phy_add(PHY_POLL, 1, &stmmac0_fixed_phy_status, -1); |
557e2a39 GC |
271 | and the second one, with a real PHY device attached to the bus, |
272 | by using the stmmac_mdio_bus_data structure (to provide the id, the | |
273 | reset procedure etc). | |
274 | ||
233b36cf GC |
275 | Note that, starting from new chips, where it is available the HW capability |
276 | register, many configurations are discovered at run-time for example to | |
277 | understand if EEE, HW csum, PTP, enhanced descriptor etc are actually | |
278 | available. As strategy adopted in this driver, the information from the HW | |
279 | capability register can replace what has been passed from the platform. | |
280 | ||
281 | 4.10) Device-tree support. | |
282 | ||
283 | Please see the following document: | |
284 | Documentation/devicetree/bindings/net/stmmac.txt | |
285 | ||
233b36cf | 286 | 4.11) This is a summary of the content of some relevant files: |
c6c60dae PM |
287 | o stmmac_main.c: implements the main network device driver; |
288 | o stmmac_mdio.c: provides MDIO functions; | |
289 | o stmmac_pci: this is the PCI driver; | |
290 | o stmmac_platform.c: this the platform driver (OF supported); | |
291 | o stmmac_ethtool.c: implements the ethtool support; | |
557e2a39 GC |
292 | o stmmac.h: private driver structure; |
293 | o common.h: common definitions and VFTs; | |
0b7a43d3 AT |
294 | o mmc_core.c/mmc.h: Management MAC Counters; |
295 | o stmmac_hwtstamp.c: HW timestamp support for PTP; | |
296 | o stmmac_ptp.c: PTP 1588 clock; | |
70523e63 | 297 | o stmmac_pcs.h: Physical Coding Sublayer common implementation; |
0b7a43d3 AT |
298 | o dwmac-<XXX>.c: these are for the platform glue-logic file; e.g. dwmac-sti.c |
299 | for STMicroelectronics SoCs. | |
300 | ||
301 | - GMAC 3.x | |
557e2a39 | 302 | o descs.h: descriptor structure definitions; |
233b36cf GC |
303 | o dwmac1000_core.c: dwmac GiGa core functions; |
304 | o dwmac1000_dma.c: dma functions for the GMAC chip; | |
305 | o dwmac1000.h: specific header file for the dwmac GiGa; | |
306 | o dwmac100_core: dwmac 100 core code; | |
307 | o dwmac100_dma.c: dma functions for the dwmac 100 chip; | |
557e2a39 | 308 | o dwmac1000.h: specific header file for the MAC; |
233b36cf | 309 | o dwmac_lib.c: generic DMA functions; |
0ec2ccd0 GC |
310 | o enh_desc.c: functions for handling enhanced descriptors; |
311 | o norm_desc.c: functions for handling normal descriptors; | |
312 | o chain_mode.c/ring_mode.c:: functions to manage RING/CHAINED modes; | |
0b7a43d3 AT |
313 | |
314 | - GMAC4.x generation | |
315 | o dwmac4_core.c: dwmac GMAC4.x core functions; | |
316 | o dwmac4_desc.c: functions for handling GMAC4.x descriptors; | |
317 | o dwmac4_descs.h: descriptor definitions; | |
318 | o dwmac4_dma.c: dma functions for the GMAC4.x chip; | |
319 | o dwmac4_dma.h: dma definitions for the GMAC4.x chip; | |
320 | o dwmac4.h: core definitions for the GMAC4.x chip; | |
321 | o dwmac4_lib.c: generic GMAC4.x functions; | |
322 | ||
323 | 4.12) TSO support (GMAC4.x) | |
324 | ||
325 | TSO (Tcp Segmentation Offload) feature is supported by GMAC 4.x chip family. | |
326 | When a packet is sent through TCP protocol, the TCP stack ensures that | |
327 | the SKB provided to the low level driver (stmmac in our case) matches with | |
328 | the maximum frame len (IP header + TCP header + payload <= 1500 bytes (for | |
329 | MTU set to 1500)). It means that if an application using TCP want to send a | |
330 | packet which will have a length (after adding headers) > 1514 the packet | |
331 | will be split in several TCP packets: The data payload is split and headers | |
332 | (TCP/IP ..) are added. It is done by software. | |
333 | ||
334 | When TSO is enabled, the TCP stack doesn't care about the maximum frame | |
335 | length and provide SKB packet to stmmac as it is. The GMAC IP will have to | |
336 | perform the segmentation by it self to match with maximum frame length. | |
337 | ||
338 | This feature can be enabled in device tree through "snps,tso" entry. | |
557e2a39 | 339 | |
4f2f25f9 GC |
340 | 5) Debug Information |
341 | ||
342 | The driver exports many information i.e. internal statistics, | |
343 | debug information, MAC and DMA registers etc. | |
344 | ||
345 | These can be read in several ways depending on the | |
346 | type of the information actually needed. | |
347 | ||
348 | For example a user can be use the ethtool support | |
349 | to get statistics: e.g. using: ethtool -S ethX | |
350 | (that shows the Management counters (MMC) if supported) | |
351 | or sees the MAC/DMA registers: e.g. using: ethtool -d ethX | |
352 | ||
233b36cf | 353 | Compiling the Kernel with CONFIG_DEBUG_FS the driver will export the following |
4f2f25f9 GC |
354 | debugfs entries: |
355 | ||
356 | /sys/kernel/debug/stmmaceth/descriptors_status | |
357 | To show the DMA TX/RX descriptor rings | |
358 | ||
233b36cf GC |
359 | Developer can also use the "debug" module parameter to get further debug |
360 | information (please see: NETIF Msg Level). | |
4f2f25f9 | 361 | |
0ec2ccd0 GC |
362 | 6) Energy Efficient Ethernet |
363 | ||
364 | Energy Efficient Ethernet(EEE) enables IEEE 802.3 MAC sublayer along | |
365 | with a family of Physical layer to operate in the Low power Idle(LPI) | |
366 | mode. The EEE mode supports the IEEE 802.3 MAC operation at 100Mbps, | |
367 | 1000Mbps & 10Gbps. | |
368 | ||
369 | The LPI mode allows power saving by switching off parts of the | |
370 | communication device functionality when there is no data to be | |
371 | transmitted & received. The system on both the side of the link can | |
372 | disable some functionalities & save power during the period of low-link | |
373 | utilization. The MAC controls whether the system should enter or exit | |
374 | the LPI mode & communicate this to PHY. | |
375 | ||
376 | As soon as the interface is opened, the driver verifies if the EEE can | |
377 | be supported. This is done by looking at both the DMA HW capability | |
378 | register and the PHY devices MCD registers. | |
379 | To enter in Tx LPI mode the driver needs to have a software timer | |
380 | that enable and disable the LPI mode when there is nothing to be | |
381 | transmitted. | |
382 | ||
233b36cf | 383 | 7) Precision Time Protocol (PTP) |
94fbbbf8 GC |
384 | The driver supports the IEEE 1588-2002, Precision Time Protocol (PTP), |
385 | which enables precise synchronization of clocks in measurement and | |
386 | control systems implemented with technologies such as network | |
387 | communication. | |
388 | ||
389 | In addition to the basic timestamp features mentioned in IEEE 1588-2002 | |
390 | Timestamps, new GMAC cores support the advanced timestamp features. | |
391 | IEEE 1588-2008 that can be enabled when configure the Kernel. | |
392 | ||
c6c60dae | 393 | 8) SGMII/RGMII support |
94fbbbf8 GC |
394 | New GMAC devices provide own way to manage RGMII/SGMII. |
395 | This information is available at run-time by looking at the | |
396 | HW capability register. This means that the stmmac can manage | |
c6c60dae | 397 | auto-negotiation and link status w/o using the PHYLIB stuff. |
94fbbbf8 GC |
398 | In fact, the HW provides a subset of extended registers to |
399 | restart the ANE, verify Full/Half duplex mode and Speed. | |
c6c60dae | 400 | Thanks to these registers, it is possible to look at the |
94fbbbf8 | 401 | Auto-negotiated Link Parter Ability. |