1 .. SPDX-License-Identifier: GPL-2.0+
2
3 ==============================================================
4 Linux Driver for the Synopsys(R) Ethernet Controllers "stmmac"
5 ==============================================================
6
7 Authors: Giuseppe Cavallaro <peppe.cavallaro@st.com>,
8 Alexandre Torgue <alexandre.torgue@st.com>, Jose Abreu <joabreu@synopsys.com>
9
10 Contents
11 ========
12
13 - In This Release
14 - Feature List
15 - Kernel Configuration
16 - Command Line Parameters
17 - Driver Information and Notes
18 - Debug Information
19 - Support
20
21 In This Release
22 ===============
23
24 This file describes the stmmac Linux Driver for all the Synopsys(R) Ethernet
25 Controllers.
26
27 Currently, this network device driver is for all STi embedded MAC/GMAC
28 (i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XILINX XC2V3000
29 FF1152AMT0221 D1215994A VIRTEX FPGA board. The Synopsys Ethernet QoS 5.0 IPK
30 is also supported.
31
32 DesignWare(R) Cores Ethernet MAC 10/100/1000 Universal version 3.70a
33 (and older) and DesignWare(R) Cores Ethernet Quality-of-Service version 4.0
34 (and upper) have been used for developing this driver as well as
35 DesignWare(R) Cores XGMAC - 10G Ethernet MAC and DesignWare(R) Cores
36 Enterprise MAC - 100G Ethernet MAC.
37
38 This driver supports both the platform bus and PCI.
39
40 This driver includes support for the following Synopsys(R) DesignWare(R)
41 Cores Ethernet Controllers and corresponding minimum and maximum versions:
42
43 +-------------------------------+--------------+--------------+--------------+
44 | Controller Name | Min. Version | Max. Version | Abbrev. Name |
45 +===============================+==============+==============+==============+
46 | Ethernet MAC Universal | N/A | 3.73a | GMAC |
47 +-------------------------------+--------------+--------------+--------------+
48 | Ethernet Quality-of-Service | 4.00a | N/A | GMAC4+ |
49 +-------------------------------+--------------+--------------+--------------+
50 | XGMAC - 10G Ethernet MAC | 2.10a | N/A | XGMAC2+ |
51 +-------------------------------+--------------+--------------+--------------+
52 | XLGMAC - 100G Ethernet MAC | 2.00a | N/A | XLGMAC2+ |
53 +-------------------------------+--------------+--------------+--------------+
54
55 For questions related to hardware requirements, refer to the documentation
56 supplied with your Ethernet adapter. All hardware requirements listed apply
57 to use with Linux.
58
59 Feature List
60 ============
61
62 The following features are available in this driver:
63 - GMII/MII/RGMII/SGMII/RMII/XGMII/XLGMII Interface
64 - Half-Duplex / Full-Duplex Operation
65 - Energy Efficient Ethernet (EEE)
66 - IEEE 802.3x PAUSE Packets (Flow Control)
67 - RMON/MIB Counters
68 - IEEE 1588 Timestamping (PTP)
69 - Pulse-Per-Second Output (PPS)
70 - MDIO Clause 22 / Clause 45 Interface
71 - MAC Loopback
72 - ARP Offloading
73 - Automatic CRC / PAD Insertion and Checking
74 - Checksum Offload for Received and Transmitted Packets
75 - Standard or Jumbo Ethernet Packets
76 - Source Address Insertion / Replacement
77 - VLAN TAG Insertion / Replacement / Deletion / Filtering (HASH and PERFECT)
78 - Programmable TX and RX Watchdog and Coalesce Settings
79 - Destination Address Filtering (PERFECT)
80 - HASH Filtering (Multicast)
81 - Layer 3 / Layer 4 Filtering
82 - Remote Wake-Up Detection
83 - Receive Side Scaling (RSS)
84 - Frame Preemption for TX and RX
85 - Programmable Burst Length, Threshold, Queue Size
86 - Multiple Queues (up to 8)
87 - Multiple Scheduling Algorithms (TX: WRR, DWRR, WFQ, SP, CBS, EST, TBS;
88 RX: WRR, SP)
89 - Flexible RX Parser
90 - TCP / UDP Segmentation Offload (TSO, USO)
91 - Split Header (SPH)
92 - Safety Features (ECC Protection, Data Parity Protection)
93 - Selftests using Ethtool
94
95 Kernel Configuration
96 ====================
97
98 The kernel configuration option is ``CONFIG_STMMAC_ETH``:
99 - ``CONFIG_STMMAC_PLATFORM``: is to enable the platform driver.
100 - ``CONFIG_STMMAC_PCI``: is to enable the pci driver.
101
102 Command Line Parameters
103 =======================
104
105 If the driver is built as a module the following optional parameters are used
106 by entering them on the command line with the modprobe command using this
107 syntax (e.g. for PCI module)::
108
109 modprobe stmmac_pci [<option>=<VAL1>,<VAL2>,...]
110
111 Driver parameters can be also passed in command line by using::
112
113 stmmaceth=watchdog:100,chain_mode=1
114
115 The default value for each parameter is generally the recommended setting,
116 unless otherwise noted.
117
118 watchdog
119 --------
120 :Valid Range: 5000-None
121 :Default Value: 5000
122
123 This parameter overrides the transmit timeout in milliseconds.
124
125 debug
126 -----
127 :Valid Range: 0-16 (0=none,...,16=all)
128 :Default Value: 0
129
130 This parameter adjusts the level of debug messages displayed in the system
131 logs.
132
133 phyaddr
134 -------
135 :Valid Range: 0-31
136 :Default Value: -1
137
138 This parameter overrides the physical address of the PHY device.
139
140 flow_ctrl
141 ---------
142 :Valid Range: 0-3 (0=off,1=rx,2=tx,3=rx/tx)
143 :Default Value: 3
144
145 This parameter changes the default Flow Control ability.
146
147 pause
148 -----
149 :Valid Range: 0-65535
150 :Default Value: 65535
151
152 This parameter changes the default Flow Control Pause time.
153
154 tc
155 --
156 :Valid Range: 64-256
157 :Default Value: 64
158
159 This parameter changes the default HW FIFO Threshold control value.
160
161 buf_sz
162 ------
163 :Valid Range: 1536-16384
164 :Default Value: 1536
165
166 This parameter changes the default RX DMA packet buffer size.
167
168 eee_timer
169 ---------
170 :Valid Range: 0-None
171 :Default Value: 1000
172
173 This parameter changes the default LPI TX Expiration time in milliseconds.
174
175 chain_mode
176 ----------
177 :Valid Range: 0-1 (0=off,1=on)
178 :Default Value: 0
179
180 This parameter changes the default mode of operation from Ring Mode to
181 Chain Mode.
182
183 Driver Information and Notes
184 ============================
185
186 Transmit Process
187 ----------------
188
189 The xmit method is invoked when the kernel needs to transmit a packet; it sets
190 the descriptors in the ring and informs the DMA engine that there is a packet
191 ready to be transmitted.
192
193 By default, the driver sets the ``NETIF_F_SG`` bit in the features field of
194 the ``net_device`` structure, enabling the scatter-gather feature. This is
195 true on chips and configurations where the checksum can be done in hardware.
196
197 Once the controller has finished transmitting the packet, timer will be
198 scheduled to release the transmit resources.
199
200 Receive Process
201 ---------------
202
203 When one or more packets are received, an interrupt happens. The interrupts
204 are not queued, so the driver has to scan all the descriptors in the ring
205 during the receive process.
206
207 This is based on NAPI, so the interrupt handler signals only if there is work
208 to be done, and it exits. Then the poll method will be scheduled at some
209 future point.
210
211 The incoming packets are stored, by the DMA, in a list of pre-allocated socket
212 buffers in order to avoid the memcpy (zero-copy).
213
214 Interrupt Mitigation
215 --------------------
216
217 The driver is able to mitigate the number of its DMA interrupts using NAPI for
218 the reception on chips older than the 3.50. New chips have an HW RX Watchdog
219 used for this mitigation.
220
221 Mitigation parameters can be tuned by ethtool.
222
223 WoL
224 ---
225
226 Wake up on Lan feature through Magic and Unicast frames are supported for the
227 GMAC, GMAC4/5 and XGMAC core.
228
229 DMA Descriptors
230 ---------------
231
232 Driver handles both normal and alternate descriptors. The latter has been only
233 tested on DesignWare(R) Cores Ethernet MAC Universal version 3.41a and later.
234
235 stmmac supports DMA descriptor to operate both in dual buffer (RING) and
236 linked-list(CHAINED) mode. In RING each descriptor points to two data buffer
237 pointers whereas in CHAINED mode they point to only one data buffer pointer.
238 RING mode is the default.
239
240 In CHAINED mode each descriptor will have pointer to next descriptor in the
241 list, hence creating the explicit chaining in the descriptor itself, whereas
242 such explicit chaining is not possible in RING mode.
243
244 Extended Descriptors
245 --------------------
246
247 The extended descriptors give us information about the Ethernet payload when
248 it is carrying PTP packets or TCP/UDP/ICMP over IP. These are not available on
249 GMAC Synopsys(R) chips older than the 3.50. At probe time the driver will
250 decide if these can be actually used. This support also is mandatory for PTPv2
251 because the extra descriptors are used for saving the hardware timestamps and
252 Extended Status.
253
254 Ethtool Support
255 ---------------
256
257 Ethtool is supported. For example, driver statistics (including RMON),
258 internal errors can be taken using::
259
260 ethtool -S ethX
261
262 Ethtool selftests are also supported. This allows to do some early sanity
263 checks to the HW using MAC and PHY loopback mechanisms::
264
265 ethtool -t ethX
266
267 Jumbo and Segmentation Offloading
268 ---------------------------------
269
270 Jumbo frames are supported and tested for the GMAC. The GSO has been also
271 added but it's performed in software. LRO is not supported.
272
273 TSO Support
274 -----------
275
276 TSO (TCP Segmentation Offload) feature is supported by GMAC > 4.x and XGMAC
277 chip family. When a packet is sent through TCP protocol, the TCP stack ensures
278 that the SKB provided to the low level driver (stmmac in our case) matches
279 with the maximum frame len (IP header + TCP header + payload <= 1500 bytes
280 (for MTU set to 1500)). It means that if an application using TCP want to send
281 a packet which will have a length (after adding headers) > 1514 the packet
282 will be split in several TCP packets: The data payload is split and headers
283 (TCP/IP ..) are added. It is done by software.
284
285 When TSO is enabled, the TCP stack doesn't care about the maximum frame length
286 and provide SKB packet to stmmac as it is. The GMAC IP will have to perform
287 the segmentation by it self to match with maximum frame length.
288
289 This feature can be enabled in device tree through ``snps,tso`` entry.
290
291 Energy Efficient Ethernet
292 -------------------------
293
294 Energy Efficient Ethernet (EEE) enables IEEE 802.3 MAC sublayer along with a
295 family of Physical layer to operate in the Low Power Idle (LPI) mode. The EEE
296 mode supports the IEEE 802.3 MAC operation at 100Mbps, 1000Mbps and 1Gbps.
297
298 The LPI mode allows power saving by switching off parts of the communication
299 device functionality when there is no data to be transmitted & received.
300 The system on both the side of the link can disable some functionalities and
301 save power during the period of low-link utilization. The MAC controls whether
302 the system should enter or exit the LPI mode and communicate this to PHY.
303
304 As soon as the interface is opened, the driver verifies if the EEE can be
305 supported. This is done by looking at both the DMA HW capability register and
306 the PHY devices MCD registers.
307
308 To enter in TX LPI mode the driver needs to have a software timer that enable
309 and disable the LPI mode when there is nothing to be transmitted.
310
311 Precision Time Protocol (PTP)
312 -----------------------------
313
314 The driver supports the IEEE 1588-2002, Precision Time Protocol (PTP), which
315 enables precise synchronization of clocks in measurement and control systems
316 implemented with technologies such as network communication.
317
318 In addition to the basic timestamp features mentioned in IEEE 1588-2002
319 Timestamps, new GMAC cores support the advanced timestamp features.
320 IEEE 1588-2008 can be enabled when configuring the Kernel.
321
322 SGMII/RGMII Support
323 -------------------
324
325 New GMAC devices provide own way to manage RGMII/SGMII. This information is
326 available at run-time by looking at the HW capability register. This means
327 that the stmmac can manage auto-negotiation and link status w/o using the
328 PHYLIB stuff. In fact, the HW provides a subset of extended registers to
329 restart the ANE, verify Full/Half duplex mode and Speed. Thanks to these
330 registers, it is possible to look at the Auto-negotiated Link Parter Ability.
331
332 Physical
333 --------
334
335 The driver is compatible with Physical Abstraction Layer to be connected with
336 PHY and GPHY devices.
337
338 Platform Information
339 --------------------
340
341 Several information can be passed through the platform and device-tree.
342
343 ::
344
345 struct plat_stmmacenet_data {
346
347 1) Bus identifier::
348
349 int bus_id;
350
351 2) PHY Physical Address. If set to -1 the driver will pick the first PHY it
352 finds::
353
354 int phy_addr;
355
356 3) PHY Device Interface::
357
358 int interface;
359
360 4) Specific platform fields for the MDIO bus::
361
362 struct stmmac_mdio_bus_data *mdio_bus_data;
363
364 5) Internal DMA parameters::
365
366 struct stmmac_dma_cfg *dma_cfg;
367
368 6) Fixed CSR Clock Range selection::
369
370 int clk_csr;
371
372 7) HW uses the GMAC core::
373
374 int has_gmac;
375
376 8) If set the MAC will use Enhanced Descriptors::
377
378 int enh_desc;
379
380 9) Core is able to perform TX Checksum and/or RX Checksum in HW::
381
382 int tx_coe;
383 int rx_coe;
384
385 11) Some HWs are not able to perform the csum in HW for over-sized frames due
386 to limited buffer sizes. Setting this flag the csum will be done in SW on
387 JUMBO frames::
388
389 int bugged_jumbo;
390
391 12) Core has the embedded power module::
392
393 int pmt;
394
395 13) Force DMA to use the Store and Forward mode or Threshold mode::
396
397 int force_sf_dma_mode;
398 int force_thresh_dma_mode;
399
400 15) Force to disable the RX Watchdog feature and switch to NAPI mode::
401
402 int riwt_off;
403
404 16) Limit the maximum operating speed and MTU::
405
406 int max_speed;
407 int maxmtu;
408
409 18) Number of Multicast/Unicast filters::
410
411 int multicast_filter_bins;
412 int unicast_filter_entries;
413
414 20) Limit the maximum TX and RX FIFO size::
415
416 int tx_fifo_size;
417 int rx_fifo_size;
418
419 21) Use the specified number of TX and RX Queues::
420
421 u32 rx_queues_to_use;
422 u32 tx_queues_to_use;
423
424 22) Use the specified TX and RX scheduling algorithm::
425
426 u8 rx_sched_algorithm;
427 u8 tx_sched_algorithm;
428
429 23) Internal TX and RX Queue parameters::
430
431 struct stmmac_rxq_cfg rx_queues_cfg[MTL_MAX_RX_QUEUES];
432 struct stmmac_txq_cfg tx_queues_cfg[MTL_MAX_TX_QUEUES];
433
434 24) This callback is used for modifying some syscfg registers (on ST SoCs)
435 according to the link speed negotiated by the physical layer::
436
437 void (*fix_mac_speed)(void *priv, unsigned int speed);
438
439 25) Callbacks used for calling a custom initialization; This is sometimes
440 necessary on some platforms (e.g. ST boxes) where the HW needs to have set
441 some PIO lines or system cfg registers. init/exit callbacks should not use
442 or modify platform data::
443
444 int (*init)(struct platform_device *pdev, void *priv);
445 void (*exit)(struct platform_device *pdev, void *priv);
446
447 26) Perform HW setup of the bus. For example, on some ST platforms this field
448 is used to configure the AMBA bridge to generate more efficient STBus traffic::
449
450 struct mac_device_info *(*setup)(void *priv);
451 void *bsp_priv;
452
453 27) Internal clocks and rates::
454
455 struct clk *stmmac_clk;
456 struct clk *pclk;
457 struct clk *clk_ptp_ref;
458 unsigned int clk_ptp_rate;
459 unsigned int clk_ref_rate;
460 s32 ptp_max_adj;
461
462 28) Main reset::
463
464 struct reset_control *stmmac_rst;
465
466 29) AXI Internal Parameters::
467
468 struct stmmac_axi *axi;
469
470 30) HW uses GMAC>4 cores::
471
472 int has_gmac4;
473
474 31) HW is sun8i based::
475
476 bool has_sun8i;
477
478 32) Enables TSO feature::
479
480 bool tso_en;
481
482 33) Enables Receive Side Scaling (RSS) feature::
483
484 int rss_en;
485
486 34) MAC Port selection::
487
488 int mac_port_sel_speed;
489
490 35) Enables TX LPI Clock Gating::
491
492 bool en_tx_lpi_clockgating;
493
494 36) HW uses XGMAC>2.10 cores::
495
496 int has_xgmac;
497
498 ::
499
500 }
501
502 For MDIO bus data, we have:
503
504 ::
505
506 struct stmmac_mdio_bus_data {
507
508 1) PHY mask passed when MDIO bus is registered::
509
510 unsigned int phy_mask;
511
512 2) List of IRQs, one per PHY::
513
514 int *irqs;
515
516 3) If IRQs is NULL, use this for probed PHY::
517
518 int probed_phy_irq;
519
520 4) Set to true if PHY needs reset::
521
522 bool needs_reset;
523
524 ::
525
526 }
527
528 For DMA engine configuration, we have:
529
530 ::
531
532 struct stmmac_dma_cfg {
533
534 1) Programmable Burst Length (TX and RX)::
535
536 int pbl;
537
538 2) If set, DMA TX / RX will use this value rather than pbl::
539
540 int txpbl;
541 int rxpbl;
542
543 3) Enable 8xPBL::
544
545 bool pblx8;
546
547 4) Enable Fixed or Mixed burst::
548
549 int fixed_burst;
550 int mixed_burst;
551
552 5) Enable Address Aligned Beats::
553
554 bool aal;
555
556 6) Enable Enhanced Addressing (> 32 bits)::
557
558 bool eame;
559
560 ::
561
562 }
563
564 For DMA AXI parameters, we have:
565
566 ::
567
568 struct stmmac_axi {
569
570 1) Enable AXI LPI::
571
572 bool axi_lpi_en;
573 bool axi_xit_frm;
574
575 2) Set AXI Write / Read maximum outstanding requests::
576
577 u32 axi_wr_osr_lmt;
578 u32 axi_rd_osr_lmt;
579
580 3) Set AXI 4KB bursts::
581
582 bool axi_kbbe;
583
584 4) Set AXI maximum burst length map::
585
586 u32 axi_blen[AXI_BLEN];
587
588 5) Set AXI Fixed burst / mixed burst::
589
590 bool axi_fb;
591 bool axi_mb;
592
593 6) Set AXI rebuild incrx mode::
594
595 bool axi_rb;
596
597 ::
598
599 }
600
601 For the RX Queues configuration, we have:
602
603 ::
604
605 struct stmmac_rxq_cfg {
606
607 1) Mode to use (DCB or AVB)::
608
609 u8 mode_to_use;
610
611 2) DMA channel to use::
612
613 u32 chan;
614
615 3) Packet routing, if applicable::
616
617 u8 pkt_route;
618
619 4) Use priority routing, and priority to route::
620
621 bool use_prio;
622 u32 prio;
623
624 ::
625
626 }
627
628 For the TX Queues configuration, we have:
629
630 ::
631
632 struct stmmac_txq_cfg {
633
634 1) Queue weight in scheduler::
635
636 u32 weight;
637
638 2) Mode to use (DCB or AVB)::
639
640 u8 mode_to_use;
641
642 3) Credit Base Shaper Parameters::
643
644 u32 send_slope;
645 u32 idle_slope;
646 u32 high_credit;
647 u32 low_credit;
648
649 4) Use priority scheduling, and priority::
650
651 bool use_prio;
652 u32 prio;
653
654 ::
655
656 }
657
658 Device Tree Information
659 -----------------------
660
661 Please refer to the following document:
662 Documentation/devicetree/bindings/net/snps,dwmac.yaml
663
664 HW Capabilities
665 ---------------
666
667 Note that, starting from new chips, where it is available the HW capability
668 register, many configurations are discovered at run-time for example to
669 understand if EEE, HW csum, PTP, enhanced descriptor etc are actually
670 available. As strategy adopted in this driver, the information from the HW
671 capability register can replace what has been passed from the platform.
672
673 Debug Information
674 =================
675
676 The driver exports many information i.e. internal statistics, debug
677 information, MAC and DMA registers etc.
678
679 These can be read in several ways depending on the type of the information
680 actually needed.
681
682 For example a user can be use the ethtool support to get statistics: e.g.
683 using: ``ethtool -S ethX`` (that shows the Management counters (MMC) if
684 supported) or sees the MAC/DMA registers: e.g. using: ``ethtool -d ethX``
685
686 Compiling the Kernel with ``CONFIG_DEBUG_FS`` the driver will export the
687 following debugfs entries:
688
689 - ``descriptors_status``: To show the DMA TX/RX descriptor rings
690 - ``dma_cap``: To show the HW Capabilities
691
692 Developer can also use the ``debug`` module parameter to get further debug
693 information (please see: NETIF Msg Level).
694
695 Support
696 =======
697
698 If an issue is identified with the released source code on a supported kernel
699 with a supported adapter, email the specific information related to the
700 issue to netdev@vger.kernel.org
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.