701 lines · plain
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 10Contents11========12 13- In This Release14- Feature List15- Kernel Configuration16- Command Line Parameters17- Driver Information and Notes18- Debug Information19- Support20 21In This Release22===============23 24This file describes the stmmac Linux Driver for all the Synopsys(R) Ethernet25Controllers.26 27Currently, this network device driver is for all STi embedded MAC/GMAC28(i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XILINX XC2V300029FF1152AMT0221 D1215994A VIRTEX FPGA board. The Synopsys Ethernet QoS 5.0 IPK30is also supported.31 32DesignWare(R) Cores Ethernet MAC 10/100/1000 Universal version 3.70a33(and older) and DesignWare(R) Cores Ethernet Quality-of-Service version 4.034(and upper) have been used for developing this driver as well as35DesignWare(R) Cores XGMAC - 10G Ethernet MAC and DesignWare(R) Cores36Enterprise 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 documentation56supplied with your Ethernet adapter. All hardware requirements listed apply57to use with Linux.58 59Feature List60============61 62The following features are available in this driver:63 - GMII/MII/RGMII/SGMII/RMII/XGMII/XLGMII Interface64 - Half-Duplex / Full-Duplex Operation65 - Energy Efficient Ethernet (EEE)66 - IEEE 802.3x PAUSE Packets (Flow Control)67 - RMON/MIB Counters68 - IEEE 1588 Timestamping (PTP)69 - Pulse-Per-Second Output (PPS)70 - MDIO Clause 22 / Clause 45 Interface71 - MAC Loopback72 - ARP Offloading73 - Automatic CRC / PAD Insertion and Checking74 - Checksum Offload for Received and Transmitted Packets75 - Standard or Jumbo Ethernet Packets76 - Source Address Insertion / Replacement77 - VLAN TAG Insertion / Replacement / Deletion / Filtering (HASH and PERFECT)78 - Programmable TX and RX Watchdog and Coalesce Settings79 - Destination Address Filtering (PERFECT)80 - HASH Filtering (Multicast)81 - Layer 3 / Layer 4 Filtering82 - Remote Wake-Up Detection83 - Receive Side Scaling (RSS)84 - Frame Preemption for TX and RX85 - Programmable Burst Length, Threshold, Queue Size86 - Multiple Queues (up to 8)87 - Multiple Scheduling Algorithms (TX: WRR, DWRR, WFQ, SP, CBS, EST, TBS;88 RX: WRR, SP)89 - Flexible RX Parser90 - TCP / UDP Segmentation Offload (TSO, USO)91 - Split Header (SPH)92 - Safety Features (ECC Protection, Data Parity Protection)93 - Selftests using Ethtool94 95Kernel Configuration96====================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 Parameters103=======================104 105If the driver is built as a module the following optional parameters are used106by entering them on the command line with the modprobe command using this107syntax (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=1114 115The default value for each parameter is generally the recommended setting,116unless otherwise noted.117 118watchdog119--------120:Valid Range: 5000-None121:Default Value: 5000122 123This parameter overrides the transmit timeout in milliseconds.124 125debug126-----127:Valid Range: 0-16 (0=none,...,16=all)128:Default Value: 0129 130This parameter adjusts the level of debug messages displayed in the system131logs.132 133phyaddr134-------135:Valid Range: 0-31136:Default Value: -1137 138This parameter overrides the physical address of the PHY device.139 140flow_ctrl141---------142:Valid Range: 0-3 (0=off,1=rx,2=tx,3=rx/tx)143:Default Value: 3144 145This parameter changes the default Flow Control ability.146 147pause148-----149:Valid Range: 0-65535150:Default Value: 65535151 152This parameter changes the default Flow Control Pause time.153 154tc155--156:Valid Range: 64-256157:Default Value: 64158 159This parameter changes the default HW FIFO Threshold control value.160 161buf_sz162------163:Valid Range: 1536-16384164:Default Value: 1536165 166This parameter changes the default RX DMA packet buffer size.167 168eee_timer169---------170:Valid Range: 0-None171:Default Value: 1000172 173This parameter changes the default LPI TX Expiration time in milliseconds.174 175chain_mode176----------177:Valid Range: 0-1 (0=off,1=on)178:Default Value: 0179 180This parameter changes the default mode of operation from Ring Mode to181Chain Mode.182 183Driver Information and Notes184============================185 186Transmit Process187----------------188 189The xmit method is invoked when the kernel needs to transmit a packet; it sets190the descriptors in the ring and informs the DMA engine that there is a packet191ready to be transmitted.192 193By default, the driver sets the ``NETIF_F_SG`` bit in the features field of194the ``net_device`` structure, enabling the scatter-gather feature. This is195true on chips and configurations where the checksum can be done in hardware.196 197Once the controller has finished transmitting the packet, timer will be198scheduled to release the transmit resources.199 200Receive Process201---------------202 203When one or more packets are received, an interrupt happens. The interrupts204are not queued, so the driver has to scan all the descriptors in the ring205during the receive process.206 207This is based on NAPI, so the interrupt handler signals only if there is work208to be done, and it exits. Then the poll method will be scheduled at some209future point.210 211The incoming packets are stored, by the DMA, in a list of pre-allocated socket212buffers in order to avoid the memcpy (zero-copy).213 214Interrupt Mitigation215--------------------216 217The driver is able to mitigate the number of its DMA interrupts using NAPI for218the reception on chips older than the 3.50. New chips have an HW RX Watchdog219used for this mitigation.220 221Mitigation parameters can be tuned by ethtool.222 223WoL224---225 226Wake up on Lan feature through Magic and Unicast frames are supported for the227GMAC, GMAC4/5 and XGMAC core.228 229DMA Descriptors230---------------231 232Driver handles both normal and alternate descriptors. The latter has been only233tested on DesignWare(R) Cores Ethernet MAC Universal version 3.41a and later.234 235stmmac supports DMA descriptor to operate both in dual buffer (RING) and236linked-list(CHAINED) mode. In RING each descriptor points to two data buffer237pointers 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 the241list, hence creating the explicit chaining in the descriptor itself, whereas242such explicit chaining is not possible in RING mode.243 244Extended Descriptors245--------------------246 247The extended descriptors give us information about the Ethernet payload when248it is carrying PTP packets or TCP/UDP/ICMP over IP. These are not available on249GMAC Synopsys(R) chips older than the 3.50. At probe time the driver will250decide if these can be actually used. This support also is mandatory for PTPv2251because the extra descriptors are used for saving the hardware timestamps and252Extended Status.253 254Ethtool Support255---------------256 257Ethtool is supported. For example, driver statistics (including RMON),258internal errors can be taken using::259 260 ethtool -S ethX261 262Ethtool selftests are also supported. This allows to do some early sanity263checks to the HW using MAC and PHY loopback mechanisms::264 265 ethtool -t ethX266 267Jumbo and Segmentation Offloading268---------------------------------269 270Jumbo frames are supported and tested for the GMAC. The GSO has been also271added but it's performed in software. LRO is not supported.272 273TSO Support274-----------275 276TSO (TCP Segmentation Offload) feature is supported by GMAC > 4.x and XGMAC277chip family. When a packet is sent through TCP protocol, the TCP stack ensures278that the SKB provided to the low level driver (stmmac in our case) matches279with the maximum frame len (IP header + TCP header + payload <= 1500 bytes280(for MTU set to 1500)). It means that if an application using TCP want to send281a packet which will have a length (after adding headers) > 1514 the packet282will be split in several TCP packets: The data payload is split and headers283(TCP/IP ..) are added. It is done by software.284 285When TSO is enabled, the TCP stack doesn't care about the maximum frame length286and provide SKB packet to stmmac as it is. The GMAC IP will have to perform287the 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 Ethernet292-------------------------293 294Energy Efficient Ethernet (EEE) enables IEEE 802.3 MAC sublayer along with a295family of Physical layer to operate in the Low Power Idle (LPI) mode. The EEE296mode 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 communication299device functionality when there is no data to be transmitted & received.300The system on both the side of the link can disable some functionalities and301save power during the period of low-link utilization. The MAC controls whether302the 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 be305supported. This is done by looking at both the DMA HW capability register and306the PHY devices MCD registers.307 308To enter in TX LPI mode the driver needs to have a software timer that enable309and 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), which315enables precise synchronization of clocks in measurement and control systems316implemented with technologies such as network communication.317 318In addition to the basic timestamp features mentioned in IEEE 1588-2002319Timestamps, new GMAC cores support the advanced timestamp features.320IEEE 1588-2008 can be enabled when configuring the Kernel.321 322SGMII/RGMII Support323-------------------324 325New GMAC devices provide own way to manage RGMII/SGMII. This information is326available at run-time by looking at the HW capability register. This means327that the stmmac can manage auto-negotiation and link status w/o using the328PHYLIB stuff. In fact, the HW provides a subset of extended registers to329restart the ANE, verify Full/Half duplex mode and Speed. Thanks to these330registers, it is possible to look at the Auto-negotiated Link Parter Ability.331 332Physical333--------334 335The driver is compatible with Physical Abstraction Layer to be connected with336PHY and GPHY devices.337 338Platform Information339--------------------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 it352finds::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 due386to limited buffer sizes. Setting this flag the csum will be done in SW on387JUMBO 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 sometimes440necessary on some platforms (e.g. ST boxes) where the HW needs to have set441some PIO lines or system cfg registers. init/exit callbacks should not use442or 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 field448is 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 Information659-----------------------660 661Please refer to the following document:662Documentation/devicetree/bindings/net/snps,dwmac.yaml663 664HW Capabilities665---------------666 667Note that, starting from new chips, where it is available the HW capability668register, many configurations are discovered at run-time for example to669understand if EEE, HW csum, PTP, enhanced descriptor etc are actually670available. As strategy adopted in this driver, the information from the HW671capability register can replace what has been passed from the platform.672 673Debug Information674=================675 676The driver exports many information i.e. internal statistics, debug677information, MAC and DMA registers etc.678 679These can be read in several ways depending on the type of the information680actually 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) if684supported) or sees the MAC/DMA registers: e.g. using: ``ethtool -d ethX``685 686Compiling the Kernel with ``CONFIG_DEBUG_FS`` the driver will export the687following debugfs entries:688 689 - ``descriptors_status``: To show the DMA TX/RX descriptor rings690 - ``dma_cap``: To show the HW Capabilities691 692Developer can also use the ``debug`` module parameter to get further debug693information (please see: NETIF Msg Level).694 695Support696=======697 698If an issue is identified with the released source code on a supported kernel699with a supported adapter, email the specific information related to the700issue to netdev@vger.kernel.org701