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