diff options
Diffstat (limited to 'Documentation/networking/device_drivers/stmicro/stmmac.rst')
-rw-r--r-- | Documentation/networking/device_drivers/stmicro/stmmac.rst | 697 |
1 files changed, 0 insertions, 697 deletions
diff --git a/Documentation/networking/device_drivers/stmicro/stmmac.rst b/Documentation/networking/device_drivers/stmicro/stmmac.rst deleted file mode 100644 index c34bab3d2df0..000000000000 --- a/Documentation/networking/device_drivers/stmicro/stmmac.rst +++ /dev/null @@ -1,697 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0+ - -============================================================== -Linux Driver for the Synopsys(R) Ethernet Controllers "stmmac" -============================================================== - -Authors: Giuseppe Cavallaro <peppe.cavallaro@st.com>, -Alexandre Torgue <alexandre.torgue@st.com>, Jose Abreu <joabreu@synopsys.com> - -Contents -======== - -- In This Release -- Feature List -- Kernel Configuration -- Command Line Parameters -- Driver Information and Notes -- Debug Information -- Support - -In This Release -=============== - -This file describes the stmmac Linux Driver for all the Synopsys(R) Ethernet -Controllers. - -Currently, this network device driver is for all STi embedded MAC/GMAC -(i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XILINX XC2V3000 -FF1152AMT0221 D1215994A VIRTEX FPGA board. The Synopsys Ethernet QoS 5.0 IPK -is also supported. - -DesignWare(R) Cores Ethernet MAC 10/100/1000 Universal version 3.70a -(and older) and DesignWare(R) Cores Ethernet Quality-of-Service version 4.0 -(and upper) have been used for developing this driver as well as -DesignWare(R) Cores XGMAC - 10G Ethernet MAC. - -This driver supports both the platform bus and PCI. - -This driver includes support for the following Synopsys(R) DesignWare(R) -Cores Ethernet Controllers and corresponding minimum and maximum versions: - -+-------------------------------+--------------+--------------+--------------+ -| Controller Name | Min. Version | Max. Version | Abbrev. Name | -+===============================+==============+==============+==============+ -| Ethernet MAC Universal | N/A | 3.73a | GMAC | -+-------------------------------+--------------+--------------+--------------+ -| Ethernet Quality-of-Service | 4.00a | N/A | GMAC4+ | -+-------------------------------+--------------+--------------+--------------+ -| XGMAC - 10G Ethernet MAC | 2.10a | N/A | XGMAC2+ | -+-------------------------------+--------------+--------------+--------------+ - -For questions related to hardware requirements, refer to the documentation -supplied with your Ethernet adapter. All hardware requirements listed apply -to use with Linux. - -Feature List -============ - -The following features are available in this driver: - - GMII/MII/RGMII/SGMII/RMII/XGMII Interface - - Half-Duplex / Full-Duplex Operation - - Energy Efficient Ethernet (EEE) - - IEEE 802.3x PAUSE Packets (Flow Control) - - RMON/MIB Counters - - IEEE 1588 Timestamping (PTP) - - Pulse-Per-Second Output (PPS) - - MDIO Clause 22 / Clause 45 Interface - - MAC Loopback - - ARP Offloading - - Automatic CRC / PAD Insertion and Checking - - Checksum Offload for Received and Transmitted Packets - - Standard or Jumbo Ethernet Packets - - Source Address Insertion / Replacement - - VLAN TAG Insertion / Replacement / Deletion / Filtering (HASH and PERFECT) - - Programmable TX and RX Watchdog and Coalesce Settings - - Destination Address Filtering (PERFECT) - - HASH Filtering (Multicast) - - Layer 3 / Layer 4 Filtering - - Remote Wake-Up Detection - - Receive Side Scaling (RSS) - - Frame Preemption for TX and RX - - Programmable Burst Length, Threshold, Queue Size - - Multiple Queues (up to 8) - - Multiple Scheduling Algorithms (TX: WRR, DWRR, WFQ, SP, CBS, EST, TBS; - RX: WRR, SP) - - Flexible RX Parser - - TCP / UDP Segmentation Offload (TSO, USO) - - Split Header (SPH) - - Safety Features (ECC Protection, Data Parity Protection) - - Selftests using Ethtool - -Kernel Configuration -==================== - -The kernel configuration option is ``CONFIG_STMMAC_ETH``: - - ``CONFIG_STMMAC_PLATFORM``: is to enable the platform driver. - - ``CONFIG_STMMAC_PCI``: is to enable the pci driver. - -Command Line Parameters -======================= - -If the driver is built as a module the following optional parameters are used -by entering them on the command line with the modprobe command using this -syntax (e.g. for PCI module):: - - modprobe stmmac_pci [<option>=<VAL1>,<VAL2>,...] - -Driver parameters can be also passed in command line by using:: - - stmmaceth=watchdog:100,chain_mode=1 - -The default value for each parameter is generally the recommended setting, -unless otherwise noted. - -watchdog --------- -:Valid Range: 5000-None -:Default Value: 5000 - -This parameter overrides the transmit timeout in milliseconds. - -debug ------ -:Valid Range: 0-16 (0=none,...,16=all) -:Default Value: 0 - -This parameter adjusts the level of debug messages displayed in the system -logs. - -phyaddr -------- -:Valid Range: 0-31 -:Default Value: -1 - -This parameter overrides the physical address of the PHY device. - -flow_ctrl ---------- -:Valid Range: 0-3 (0=off,1=rx,2=tx,3=rx/tx) -:Default Value: 3 - -This parameter changes the default Flow Control ability. - -pause ------ -:Valid Range: 0-65535 -:Default Value: 65535 - -This parameter changes the default Flow Control Pause time. - -tc --- -:Valid Range: 64-256 -:Default Value: 64 - -This parameter changes the default HW FIFO Threshold control value. - -buf_sz ------- -:Valid Range: 1536-16384 -:Default Value: 1536 - -This parameter changes the default RX DMA packet buffer size. - -eee_timer ---------- -:Valid Range: 0-None -:Default Value: 1000 - -This parameter changes the default LPI TX Expiration time in milliseconds. - -chain_mode ----------- -:Valid Range: 0-1 (0=off,1=on) -:Default Value: 0 - -This parameter changes the default mode of operation from Ring Mode to -Chain Mode. - -Driver Information and Notes -============================ - -Transmit Process ----------------- - -The xmit method is invoked when the kernel needs to transmit a packet; it sets -the descriptors in the ring and informs the DMA engine that there is a packet -ready to be transmitted. - -By default, the driver sets the ``NETIF_F_SG`` bit in the features field of -the ``net_device`` structure, enabling the scatter-gather feature. This is -true on chips and configurations where the checksum can be done in hardware. - -Once the controller has finished transmitting the packet, timer will be -scheduled to release the transmit resources. - -Receive Process ---------------- - -When one or more packets are received, an interrupt happens. The interrupts -are not queued, so the driver has to scan all the descriptors in the ring -during the receive process. - -This is based on NAPI, so the interrupt handler signals only if there is work -to be done, and it exits. Then the poll method will be scheduled at some -future point. - -The incoming packets are stored, by the DMA, in a list of pre-allocated socket -buffers in order to avoid the memcpy (zero-copy). - -Interrupt Mitigation --------------------- - -The driver is able to mitigate the number of its DMA interrupts using NAPI for -the reception on chips older than the 3.50. New chips have an HW RX Watchdog -used for this mitigation. - -Mitigation parameters can be tuned by ethtool. - -WoL ---- - -Wake up on Lan feature through Magic and Unicast frames are supported for the -GMAC, GMAC4/5 and XGMAC core. - -DMA Descriptors ---------------- - -Driver handles both normal and alternate descriptors. The latter has been only -tested on DesignWare(R) Cores Ethernet MAC Universal version 3.41a and later. - -stmmac supports DMA descriptor to operate both in dual buffer (RING) and -linked-list(CHAINED) mode. In RING each descriptor points to two data buffer -pointers whereas in CHAINED mode they point to only one data buffer pointer. -RING mode is the default. - -In CHAINED mode each descriptor will have pointer to next descriptor in the -list, hence creating the explicit chaining in the descriptor itself, whereas -such explicit chaining is not possible in RING mode. - -Extended Descriptors --------------------- - -The extended descriptors give us information about the Ethernet payload when -it is carrying PTP packets or TCP/UDP/ICMP over IP. These are not available on -GMAC Synopsys(R) chips older than the 3.50. At probe time the driver will -decide if these can be actually used. This support also is mandatory for PTPv2 -because the extra descriptors are used for saving the hardware timestamps and -Extended Status. - -Ethtool Support ---------------- - -Ethtool is supported. For example, driver statistics (including RMON), -internal errors can be taken using:: - - ethtool -S ethX - -Ethtool selftests are also supported. This allows to do some early sanity -checks to the HW using MAC and PHY loopback mechanisms:: - - ethtool -t ethX - -Jumbo and Segmentation Offloading ---------------------------------- - -Jumbo frames are supported and tested for the GMAC. The GSO has been also -added but it's performed in software. LRO is not supported. - -TSO Support ------------ - -TSO (TCP Segmentation Offload) feature is supported by GMAC > 4.x and XGMAC -chip family. When a packet is sent through TCP protocol, the TCP stack ensures -that the SKB provided to the low level driver (stmmac in our case) matches -with the maximum frame len (IP header + TCP header + payload <= 1500 bytes -(for MTU set to 1500)). It means that if an application using TCP want to send -a packet which will have a length (after adding headers) > 1514 the packet -will be split in several TCP packets: The data payload is split and headers -(TCP/IP ..) are added. It is done by software. - -When TSO is enabled, the TCP stack doesn't care about the maximum frame length -and provide SKB packet to stmmac as it is. The GMAC IP will have to perform -the segmentation by it self to match with maximum frame length. - -This feature can be enabled in device tree through ``snps,tso`` entry. - -Energy Efficient Ethernet -------------------------- - -Energy Efficient Ethernet (EEE) enables IEEE 802.3 MAC sublayer along with a -family of Physical layer to operate in the Low Power Idle (LPI) mode. The EEE -mode supports the IEEE 802.3 MAC operation at 100Mbps, 1000Mbps and 1Gbps. - -The LPI mode allows power saving by switching off parts of the communication -device functionality when there is no data to be transmitted & received. -The system on both the side of the link can disable some functionalities and -save power during the period of low-link utilization. The MAC controls whether -the system should enter or exit the LPI mode and communicate this to PHY. - -As soon as the interface is opened, the driver verifies if the EEE can be -supported. This is done by looking at both the DMA HW capability register and -the PHY devices MCD registers. - -To enter in TX LPI mode the driver needs to have a software timer that enable -and disable the LPI mode when there is nothing to be transmitted. - -Precision Time Protocol (PTP) ------------------------------ - -The driver supports the IEEE 1588-2002, Precision Time Protocol (PTP), which -enables precise synchronization of clocks in measurement and control systems -implemented with technologies such as network communication. - -In addition to the basic timestamp features mentioned in IEEE 1588-2002 -Timestamps, new GMAC cores support the advanced timestamp features. -IEEE 1588-2008 can be enabled when configuring the Kernel. - -SGMII/RGMII Support -------------------- - -New GMAC devices provide own way to manage RGMII/SGMII. This information is -available at run-time by looking at the HW capability register. This means -that the stmmac can manage auto-negotiation and link status w/o using the -PHYLIB stuff. In fact, the HW provides a subset of extended registers to -restart the ANE, verify Full/Half duplex mode and Speed. Thanks to these -registers, it is possible to look at the Auto-negotiated Link Parter Ability. - -Physical --------- - -The driver is compatible with Physical Abstraction Layer to be connected with -PHY and GPHY devices. - -Platform Information --------------------- - -Several information can be passed through the platform and device-tree. - -:: - - struct plat_stmmacenet_data { - -1) Bus identifier:: - - int bus_id; - -2) PHY Physical Address. If set to -1 the driver will pick the first PHY it -finds:: - - int phy_addr; - -3) PHY Device Interface:: - - int interface; - -4) Specific platform fields for the MDIO bus:: - - struct stmmac_mdio_bus_data *mdio_bus_data; - -5) Internal DMA parameters:: - - struct stmmac_dma_cfg *dma_cfg; - -6) Fixed CSR Clock Range selection:: - - int clk_csr; - -7) HW uses the GMAC core:: - - int has_gmac; - -8) If set the MAC will use Enhanced Descriptors:: - - int enh_desc; - -9) Core is able to perform TX Checksum and/or RX Checksum in HW:: - - int tx_coe; - int rx_coe; - -11) Some HWs are not able to perform the csum in HW for over-sized frames due -to limited buffer sizes. Setting this flag the csum will be done in SW on -JUMBO frames:: - - int bugged_jumbo; - -12) Core has the embedded power module:: - - int pmt; - -13) Force DMA to use the Store and Forward mode or Threshold mode:: - - int force_sf_dma_mode; - int force_thresh_dma_mode; - -15) Force to disable the RX Watchdog feature and switch to NAPI mode:: - - int riwt_off; - -16) Limit the maximum operating speed and MTU:: - - int max_speed; - int maxmtu; - -18) Number of Multicast/Unicast filters:: - - int multicast_filter_bins; - int unicast_filter_entries; - -20) Limit the maximum TX and RX FIFO size:: - - int tx_fifo_size; - int rx_fifo_size; - -21) Use the specified number of TX and RX Queues:: - - u32 rx_queues_to_use; - u32 tx_queues_to_use; - -22) Use the specified TX and RX scheduling algorithm:: - - u8 rx_sched_algorithm; - u8 tx_sched_algorithm; - -23) Internal TX and RX Queue parameters:: - - struct stmmac_rxq_cfg rx_queues_cfg[MTL_MAX_RX_QUEUES]; - struct stmmac_txq_cfg tx_queues_cfg[MTL_MAX_TX_QUEUES]; - -24) This callback is used for modifying some syscfg registers (on ST SoCs) -according to the link speed negotiated by the physical layer:: - - void (*fix_mac_speed)(void *priv, unsigned int speed); - -25) Callbacks used for calling a custom initialization; This is sometimes -necessary on some platforms (e.g. ST boxes) where the HW needs to have set -some PIO lines or system cfg registers. init/exit callbacks should not use -or modify platform data:: - - int (*init)(struct platform_device *pdev, void *priv); - void (*exit)(struct platform_device *pdev, void *priv); - -26) Perform HW setup of the bus. For example, on some ST platforms this field -is used to configure the AMBA bridge to generate more efficient STBus traffic:: - - struct mac_device_info *(*setup)(void *priv); - void *bsp_priv; - -27) Internal clocks and rates:: - - struct clk *stmmac_clk; - struct clk *pclk; - struct clk *clk_ptp_ref; - unsigned int clk_ptp_rate; - unsigned int clk_ref_rate; - s32 ptp_max_adj; - -28) Main reset:: - - struct reset_control *stmmac_rst; - -29) AXI Internal Parameters:: - - struct stmmac_axi *axi; - -30) HW uses GMAC>4 cores:: - - int has_gmac4; - -31) HW is sun8i based:: - - bool has_sun8i; - -32) Enables TSO feature:: - - bool tso_en; - -33) Enables Receive Side Scaling (RSS) feature:: - - int rss_en; - -34) MAC Port selection:: - - int mac_port_sel_speed; - -35) Enables TX LPI Clock Gating:: - - bool en_tx_lpi_clockgating; - -36) HW uses XGMAC>2.10 cores:: - - int has_xgmac; - -:: - - } - -For MDIO bus data, we have: - -:: - - struct stmmac_mdio_bus_data { - -1) PHY mask passed when MDIO bus is registered:: - - unsigned int phy_mask; - -2) List of IRQs, one per PHY:: - - int *irqs; - -3) If IRQs is NULL, use this for probed PHY:: - - int probed_phy_irq; - -4) Set to true if PHY needs reset:: - - bool needs_reset; - -:: - - } - -For DMA engine configuration, we have: - -:: - - struct stmmac_dma_cfg { - -1) Programmable Burst Length (TX and RX):: - - int pbl; - -2) If set, DMA TX / RX will use this value rather than pbl:: - - int txpbl; - int rxpbl; - -3) Enable 8xPBL:: - - bool pblx8; - -4) Enable Fixed or Mixed burst:: - - int fixed_burst; - int mixed_burst; - -5) Enable Address Aligned Beats:: - - bool aal; - -6) Enable Enhanced Addressing (> 32 bits):: - - bool eame; - -:: - - } - -For DMA AXI parameters, we have: - -:: - - struct stmmac_axi { - -1) Enable AXI LPI:: - - bool axi_lpi_en; - bool axi_xit_frm; - -2) Set AXI Write / Read maximum outstanding requests:: - - u32 axi_wr_osr_lmt; - u32 axi_rd_osr_lmt; - -3) Set AXI 4KB bursts:: - - bool axi_kbbe; - -4) Set AXI maximum burst length map:: - - u32 axi_blen[AXI_BLEN]; - -5) Set AXI Fixed burst / mixed burst:: - - bool axi_fb; - bool axi_mb; - -6) Set AXI rebuild incrx mode:: - - bool axi_rb; - -:: - - } - -For the RX Queues configuration, we have: - -:: - - struct stmmac_rxq_cfg { - -1) Mode to use (DCB or AVB):: - - u8 mode_to_use; - -2) DMA channel to use:: - - u32 chan; - -3) Packet routing, if applicable:: - - u8 pkt_route; - -4) Use priority routing, and priority to route:: - - bool use_prio; - u32 prio; - -:: - - } - -For the TX Queues configuration, we have: - -:: - - struct stmmac_txq_cfg { - -1) Queue weight in scheduler:: - - u32 weight; - -2) Mode to use (DCB or AVB):: - - u8 mode_to_use; - -3) Credit Base Shaper Parameters:: - - u32 send_slope; - u32 idle_slope; - u32 high_credit; - u32 low_credit; - -4) Use priority scheduling, and priority:: - - bool use_prio; - u32 prio; - -:: - - } - -Device Tree Information ------------------------ - -Please refer to the following document: -Documentation/devicetree/bindings/net/snps,dwmac.yaml - -HW Capabilities ---------------- - -Note that, starting from new chips, where it is available the HW capability -register, many configurations are discovered at run-time for example to -understand if EEE, HW csum, PTP, enhanced descriptor etc are actually -available. As strategy adopted in this driver, the information from the HW -capability register can replace what has been passed from the platform. - -Debug Information -================= - -The driver exports many information i.e. internal statistics, debug -information, MAC and DMA registers etc. - -These can be read in several ways depending on the type of the information -actually needed. - -For example a user can be use the ethtool support to get statistics: e.g. -using: ``ethtool -S ethX`` (that shows the Management counters (MMC) if -supported) or sees the MAC/DMA registers: e.g. using: ``ethtool -d ethX`` - -Compiling the Kernel with ``CONFIG_DEBUG_FS`` the driver will export the -following debugfs entries: - - - ``descriptors_status``: To show the DMA TX/RX descriptor rings - - ``dma_cap``: To show the HW Capabilities - -Developer can also use the ``debug`` module parameter to get further debug -information (please see: NETIF Msg Level). - -Support -======= - -If an issue is identified with the released source code on a supported kernel -with a supported adapter, email the specific information related to the -issue to netdev@vger.kernel.org |