| STMicroelectronics 10/100/1000 Synopsys Ethernet driver |
| |
| Copyright (C) 2007-2010 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.60a (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; |
| tx_coe: Enable/Disable Tx Checksum Offload engine; |
| watchdog: transmit timeout (in milliseconds); |
| flow_ctrl: Flow control ability [on/off]; |
| pause: Flow Control Pause Time; |
| tmrate: timer period (only if timer optimisation is configured). |
| |
| 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) Timer-Driver Interrupt |
| Instead of having the device that asynchronously notifies the frame receptions, the |
| driver configures a timer to generate an interrupt at regular intervals. |
| Based on the granularity of the timer, the frames that are received by the device |
| will experience different levels of latency. Some NICs have dedicated timer |
| device to perform this task. STMMAC can use either the RTC device or the TMU |
| channel 2 on STLinux platforms. |
| The timers frequency can be passed to the driver as parameter; when change it, |
| take care of both hardware capability and network stability/performance impact. |
| Several performance tests on STM platforms showed this optimisation allows to spare |
| the CPU while having the maximum throughput. |
| |
| 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 { |
| int bus_id; |
| int phy_addr; |
| int interface; |
| struct stmmac_mdio_bus_data *mdio_bus_data; |
| int pbl; |
| 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; |
| 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 *bsp_priv; |
| }; |
| |
| Where: |
| 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 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 clk_csr: 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 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 initialisation; |
| 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: this is a custom configuration that can be passed while |
| initialising the resources. |
| |
| The we have: |
| |
| struct stmmac_mdio_bus_data { |
| int bus_id; |
| int (*phy_reset)(void *priv); |
| unsigned int phy_mask; |
| int *irqs; |
| int probed_phy_irq; |
| }; |
| |
| Where: |
| o bus_id: bus identifier; |
| 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. |
| |
| Below an example how the structures above are using on ST platforms. |
| |
| static struct plat_stmmacenet_data stxYYY_ethernet_platform_data = { |
| .pbl = 32, |
| .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 = { |
| .bus_id = 1, |
| | |
| |-> phy device on the bus_id 1 |
| .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_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 |
| |
| 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) TODO: |
| o XGMAC is not supported. |
| o Add the EEE - Energy Efficient Ethernet |
| o Add the PTP - precision time protocol |