diff options
Diffstat (limited to 'Documentation/networking/stmmac.txt')
| -rw-r--r-- | Documentation/networking/stmmac.txt | 364 |
1 files changed, 0 insertions, 364 deletions
diff --git a/Documentation/networking/stmmac.txt b/Documentation/networking/stmmac.txt deleted file mode 100644 index 654d2e55c8cb..000000000000 --- a/Documentation/networking/stmmac.txt +++ /dev/null @@ -1,364 +0,0 @@ - STMicroelectronics 10/100/1000 Synopsys Ethernet driver - -Copyright (C) 2007-2013 STMicroelectronics Ltd -Author: Giuseppe Cavallaro <peppe.cavallaro@st.com> - -This is the driver for the MAC 10/100/1000 on-chip Ethernet controllers -(Synopsys IP blocks). - -Currently this network device driver is for all STM embedded MAC/GMAC -(i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XLINX XC2V3000 -FF1152AMT0221 D1215994A VIRTEX FPGA board. - -DWC Ether MAC 10/100/1000 Universal version 3.70a (and older) and DWC Ether -MAC 10/100 Universal version 4.0 have been used for developing this driver. - -This driver supports both the platform bus and PCI. - -Please, for more information also visit: www.stlinux.com - -1) Kernel Configuration -The kernel configuration option is STMMAC_ETH: - Device Drivers ---> Network device support ---> Ethernet (1000 Mbit) ---> - STMicroelectronics 10/100/1000 Ethernet driver (STMMAC_ETH) - -2) Driver parameters list: - debug: message level (0: no output, 16: all); - phyaddr: to manually provide the physical address to the PHY device; - dma_rxsize: DMA rx ring size; - dma_txsize: DMA tx ring size; - buf_sz: DMA buffer size; - tc: control the HW FIFO threshold; - watchdog: transmit timeout (in milliseconds); - flow_ctrl: Flow control ability [on/off]; - pause: Flow Control Pause Time; - eee_timer: tx EEE timer; - chain_mode: select chain mode instead of ring. - -3) Command line options -Driver parameters can be also passed in command line by using: - stmmaceth=dma_rxsize:128,dma_txsize:512 - -4) Driver information and notes - -4.1) 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. -Once the controller has finished transmitting the packet, an interrupt is -triggered; So the driver will be able to release the socket buffers. -By default, the driver sets the NETIF_F_SG bit in the features field of the -net_device structure enabling the scatter/gather feature. - -4.2) 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). - -4.3) 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. - -On Tx-side, the mitigation schema is based on a SW timer that calls the -tx function (stmmac_tx) to reclaim the resource after transmitting the -frames. -Also there is another parameter (like a threshold) used to program -the descriptors avoiding to set the interrupt on completion bit in -when the frame is sent (xmit). - -Mitigation parameters can be tuned by ethtool. - -4.4) WOL -Wake up on Lan feature through Magic and Unicast frames are supported for the -GMAC core. - -4.5) DMA descriptors -Driver handles both normal and enhanced descriptors. The latter has been only -tested on DWC Ether MAC 10/100/1000 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. - -4.6) Ethtool support -Ethtool is supported. Driver statistics and internal errors can be taken using: -ethtool -S ethX command. It is possible to dump registers etc. - -4.7) 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. - -4.8) Physical -The driver is compatible with PAL to work with PHY and GPHY devices. - -4.9) Platform information -Several driver's information can be passed through the platform -These are included in the include/linux/stmmac.h header file -and detailed below as well: - -struct plat_stmmacenet_data { - char *phy_bus_name; - int bus_id; - int phy_addr; - int interface; - struct stmmac_mdio_bus_data *mdio_bus_data; - struct stmmac_dma_cfg *dma_cfg; - int clk_csr; - int has_gmac; - int enh_desc; - int tx_coe; - int rx_coe; - int bugged_jumbo; - int pmt; - int force_sf_dma_mode; - int riwt_off; - void (*fix_mac_speed)(void *priv, unsigned int speed); - void (*bus_setup)(void __iomem *ioaddr); - int (*init)(struct platform_device *pdev); - void (*exit)(struct platform_device *pdev); - void *custom_cfg; - void *custom_data; - void *bsp_priv; - }; - -Where: - o phy_bus_name: phy bus name to attach to the stmmac. - o bus_id: bus identifier. - o phy_addr: the physical address can be passed from the platform. - If it is set to -1 the driver will automatically - detect it at run-time by probing all the 32 addresses. - o interface: PHY device's interface. - o mdio_bus_data: specific platform fields for the MDIO bus. - o dma_cfg: internal DMA parameters - o pbl: the Programmable Burst Length is maximum number of beats to - be transferred in one DMA transaction. - GMAC also enables the 4xPBL by default. - o fixed_burst/mixed_burst/burst_len - o clk_csr: fixed CSR Clock range selection. - o has_gmac: uses the GMAC core. - o enh_desc: if sets the MAC will use the enhanced descriptor structure. - o tx_coe: core is able to perform the tx csum in HW. - o rx_coe: the supports three check sum offloading engine types: - type_1, type_2 (full csum) and no RX coe. - o bugged_jumbo: 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. - o pmt: core has the embedded power module (optional). - o force_sf_dma_mode: force DMA to use the Store and Forward mode - instead of the Threshold. - o riwt_off: force to disable the RX watchdog feature and switch to NAPI mode. - o fix_mac_speed: this callback is used for modifying some syscfg registers - (on ST SoCs) according to the link speed negotiated by the - physical layer . - o bus_setup: 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. - o init/exit: callbacks used for calling a custom initialization; - this is sometime necessary on some platforms (e.g. ST boxes) - where the HW needs to have set some PIO lines or system cfg - registers. - o custom_cfg/custom_data: this is a custom configuration that can be passed - while initializing the resources. - o bsp_priv: another private poiter. - -For MDIO bus The we have: - - struct stmmac_mdio_bus_data { - int (*phy_reset)(void *priv); - unsigned int phy_mask; - int *irqs; - int probed_phy_irq; - }; - -Where: - o phy_reset: hook to reset the phy device attached to the bus. - o phy_mask: phy mask passed when register the MDIO bus within the driver. - o irqs: list of IRQs, one per PHY. - o probed_phy_irq: if irqs is NULL, use this for probed PHY. - -For DMA engine we have the following internal fields that should be -tuned according to the HW capabilities. - -struct stmmac_dma_cfg { - int pbl; - int fixed_burst; - int burst_len_supported; -}; - -Where: - o pbl: Programmable Burst Length - o fixed_burst: program the DMA to use the fixed burst mode - o burst_len: this is the value we put in the register - supported values are provided as macros in - linux/stmmac.h header file. - ---- - -Below an example how the structures above are using on ST platforms. - - static struct plat_stmmacenet_data stxYYY_ethernet_platform_data = { - .has_gmac = 0, - .enh_desc = 0, - .fix_mac_speed = stxYYY_ethernet_fix_mac_speed, - | - |-> to write an internal syscfg - | on this platform when the - | link speed changes from 10 to - | 100 and viceversa - .init = &stmmac_claim_resource, - | - |-> On ST SoC this calls own "PAD" - | manager framework to claim - | all the resources necessary - | (GPIO ...). The .custom_cfg field - | is used to pass a custom config. -}; - -Below the usage of the stmmac_mdio_bus_data: on this SoC, in fact, -there are two MAC cores: one MAC is for MDIO Bus/PHY emulation -with fixed_link support. - -static struct stmmac_mdio_bus_data stmmac1_mdio_bus = { - .phy_reset = phy_reset; - | - |-> function to provide the phy_reset on this board - .phy_mask = 0, -}; - -static struct fixed_phy_status stmmac0_fixed_phy_status = { - .link = 1, - .speed = 100, - .duplex = 1, -}; - -During the board's device_init we can configure the first -MAC for fixed_link by calling: - fixed_phy_add(PHY_POLL, 1, &stmmac0_fixed_phy_status));) -and the second one, with a real PHY device attached to the bus, -by using the stmmac_mdio_bus_data structure (to provide the id, the -reset procedure etc). - -4.10) List of source files: - o Kconfig - o Makefile - o stmmac_main.c: main network device driver; - o stmmac_mdio.c: mdio functions; - o stmmac_pci: PCI driver; - o stmmac_platform.c: platform driver - o stmmac_ethtool.c: ethtool support; - o stmmac_timer.[ch]: timer code used for mitigating the driver dma interrupts - (only tested on ST40 platforms based); - o stmmac.h: private driver structure; - o common.h: common definitions and VFTs; - o descs.h: descriptor structure definitions; - o dwmac1000_core.c: GMAC core functions; - o dwmac1000_dma.c: dma functions for the GMAC chip; - o dwmac1000.h: specific header file for the GMAC; - o dwmac100_core: MAC 100 core and dma code; - o dwmac100_dma.c: dma funtions for the MAC chip; - o dwmac1000.h: specific header file for the MAC; - o dwmac_lib.c: generic DMA functions shared among chips; - o enh_desc.c: functions for handling enhanced descriptors; - o norm_desc.c: functions for handling normal descriptors; - o chain_mode.c/ring_mode.c:: functions to manage RING/CHAINED modes; - o mmc_core.c/mmc.h: Management MAC Counters; - o stmmac_hwtstamp.c: HW timestamp support for PTP - o stmmac_ptp.c: PTP 1588 clock - -5) 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 and enabling the -STMMAC_DEBUG_FS option the driver will export the following -debugfs entries: - -/sys/kernel/debug/stmmaceth/descriptors_status - To show the DMA TX/RX descriptor rings - -Developer can also use the "debug" module parameter to get -further debug information. - -In the end, there are other macros (that cannot be enabled -via menuconfig) to turn-on the RX/TX DMA debugging, -specific MAC core debug printk etc. Others to enable the -debug in the TX and RX processes. -All these are only useful during the developing stage -and should never enabled inside the code for general usage. -In fact, these can generate an huge amount of debug messages. - -6) 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 & 10Gbps. - -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 & save power during the period of low-link -utilization. The MAC controls whether the system should enter or exit -the LPI mode & 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. - -7) Extended descriptors -The extended descriptors give us information about the receive Ethernet payload -when it is carrying PTP packets or TCP/UDP/ICMP over IP. -These are not available on GMAC Synopsys 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 6 and 7 -are used for saving the hardware timestamps. - -8) 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 that can be enabled when configure the Kernel. - -9) SGMII/RGMII supports -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. -Also thanks to these registers it is possible to look at the -Auto-negotiated Link Parter Ability. - -10) TODO: - o XGMAC is not supported. - o Complete the TBI & RTBI support. - o extened VLAN support for 3.70a SYNP GMAC. |