1 STMicroelectronics 10/100/1000 Synopsys Ethernet driver
3 Copyright (C) 2007-2010 STMicroelectronics Ltd
4 Author: Giuseppe Cavallaro <peppe.cavallaro@st.com>
6 This is the driver for the MAC 10/100/1000 on-chip Ethernet controllers
9 Currently this network device driver is for all STM embedded MAC/GMAC
10 (i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XLINX XC2V3000
11 FF1152AMT0221 D1215994A VIRTEX FPGA board.
13 DWC Ether MAC 10/100/1000 Universal version 3.60a (and older) and DWC Ether MAC 10/100
14 Universal version 4.0 have been used for developing this driver.
16 This driver supports both the platform bus and PCI.
18 Please, for more information also visit: www.stlinux.com
20 1) Kernel Configuration
21 The kernel configuration option is STMMAC_ETH:
22 Device Drivers ---> Network device support ---> Ethernet (1000 Mbit) --->
23 STMicroelectronics 10/100/1000 Ethernet driver (STMMAC_ETH)
25 2) Driver parameters list:
26 debug: message level (0: no output, 16: all);
27 phyaddr: to manually provide the physical address to the PHY device;
28 dma_rxsize: DMA rx ring size;
29 dma_txsize: DMA tx ring size;
30 buf_sz: DMA buffer size;
31 tc: control the HW FIFO threshold;
32 tx_coe: Enable/Disable Tx Checksum Offload engine;
33 watchdog: transmit timeout (in milliseconds);
34 flow_ctrl: Flow control ability [on/off];
35 pause: Flow Control Pause Time;
36 tmrate: timer period (only if timer optimisation is configured).
38 3) Command line options
39 Driver parameters can be also passed in command line by using:
40 stmmaceth=dma_rxsize:128,dma_txsize:512
42 4) Driver information and notes
45 The xmit method is invoked when the kernel needs to transmit a packet; it sets
46 the descriptors in the ring and informs the DMA engine that there is a packet
47 ready to be transmitted.
48 Once the controller has finished transmitting the packet, an interrupt is
49 triggered; So the driver will be able to release the socket buffers.
50 By default, the driver sets the NETIF_F_SG bit in the features field of the
51 net_device structure enabling the scatter/gather feature.
54 When one or more packets are received, an interrupt happens. The interrupts
55 are not queued so the driver has to scan all the descriptors in the ring during
57 This is based on NAPI so the interrupt handler signals only if there is work to be
59 Then the poll method will be scheduled at some future point.
60 The incoming packets are stored, by the DMA, in a list of pre-allocated socket
61 buffers in order to avoid the memcpy (Zero-copy).
63 4.3) Timer-Driver Interrupt
64 Instead of having the device that asynchronously notifies the frame receptions, the
65 driver configures a timer to generate an interrupt at regular intervals.
66 Based on the granularity of the timer, the frames that are received by the device
67 will experience different levels of latency. Some NICs have dedicated timer
68 device to perform this task. STMMAC can use either the RTC device or the TMU
69 channel 2 on STLinux platforms.
70 The timers frequency can be passed to the driver as parameter; when change it,
71 take care of both hardware capability and network stability/performance impact.
72 Several performance tests on STM platforms showed this optimisation allows to spare
73 the CPU while having the maximum throughput.
76 Wake up on Lan feature through Magic and Unicast frames are supported for the GMAC
80 Driver handles both normal and enhanced descriptors. The latter has been only
81 tested on DWC Ether MAC 10/100/1000 Universal version 3.41a and later.
83 STMMAC supports DMA descriptor to operate both in dual buffer (RING)
84 and linked-list(CHAINED) mode. In RING each descriptor points to two
85 data buffer pointers whereas in CHAINED mode they point to only one data
86 buffer pointer. RING mode is the default.
88 In CHAINED mode each descriptor will have pointer to next descriptor in
89 the list, hence creating the explicit chaining in the descriptor itself,
90 whereas such explicit chaining is not possible in RING mode.
93 Ethtool is supported. Driver statistics and internal errors can be taken using:
94 ethtool -S ethX command. It is possible to dump registers etc.
96 4.7) Jumbo and Segmentation Offloading
97 Jumbo frames are supported and tested for the GMAC.
98 The GSO has been also added but it's performed in software.
102 The driver is compatible with PAL to work with PHY and GPHY devices.
104 4.9) Platform information
105 Several driver's information can be passed through the platform
106 These are included in the include/linux/stmmac.h header file
107 and detailed below as well:
109 struct plat_stmmacenet_data {
113 struct stmmac_mdio_bus_data *mdio_bus_data;
114 struct stmmac_dma_cfg *dma_cfg;
122 int force_sf_dma_mode;
123 void (*fix_mac_speed)(void *priv, unsigned int speed);
124 void (*bus_setup)(void __iomem *ioaddr);
125 int (*init)(struct platform_device *pdev);
126 void (*exit)(struct platform_device *pdev);
131 o bus_id: bus identifier.
132 o phy_addr: the physical address can be passed from the platform.
133 If it is set to -1 the driver will automatically
134 detect it at run-time by probing all the 32 addresses.
135 o interface: PHY device's interface.
136 o mdio_bus_data: specific platform fields for the MDIO bus.
137 o pbl: the Programmable Burst Length is maximum number of beats to
138 be transferred in one DMA transaction.
139 GMAC also enables the 4xPBL by default.
140 o clk_csr: fixed CSR Clock range selection.
141 o has_gmac: uses the GMAC core.
142 o enh_desc: if sets the MAC will use the enhanced descriptor structure.
143 o tx_coe: core is able to perform the tx csum in HW.
144 o rx_coe: the supports three check sum offloading engine types:
145 type_1, type_2 (full csum) and no RX coe.
146 o bugged_jumbo: some HWs are not able to perform the csum in HW for
147 over-sized frames due to limited buffer sizes.
148 Setting this flag the csum will be done in SW on
150 o pmt: core has the embedded power module (optional).
151 o force_sf_dma_mode: force DMA to use the Store and Forward mode
152 instead of the Threshold.
153 o fix_mac_speed: this callback is used for modifying some syscfg registers
154 (on ST SoCs) according to the link speed negotiated by the
156 o bus_setup: perform HW setup of the bus. For example, on some ST platforms
157 this field is used to configure the AMBA bridge to generate more
158 efficient STBus traffic.
159 o init/exit: callbacks used for calling a custom initialisation;
160 this is sometime necessary on some platforms (e.g. ST boxes)
161 where the HW needs to have set some PIO lines or system cfg
163 o custom_cfg: this is a custom configuration that can be passed while
164 initialising the resources.
166 For MDIO bus The we have:
168 struct stmmac_mdio_bus_data {
170 int (*phy_reset)(void *priv);
171 unsigned int phy_mask;
177 o bus_id: bus identifier;
178 o phy_reset: hook to reset the phy device attached to the bus.
179 o phy_mask: phy mask passed when register the MDIO bus within the driver.
180 o irqs: list of IRQs, one per PHY.
181 o probed_phy_irq: if irqs is NULL, use this for probed PHY.
184 For DMA engine we have the following internal fields that should be
185 tuned according to the HW capabilities.
187 struct stmmac_dma_cfg {
190 int burst_len_supported;
194 o pbl: Programmable Burst Length
195 o fixed_burst: program the DMA to use the fixed burst mode
196 o burst_len: this is the value we put in the register
197 supported values are provided as macros in
198 linux/stmmac.h header file.
202 Below an example how the structures above are using on ST platforms.
204 static struct plat_stmmacenet_data stxYYY_ethernet_platform_data = {
207 .fix_mac_speed = stxYYY_ethernet_fix_mac_speed,
209 |-> to write an internal syscfg
210 | on this platform when the
211 | link speed changes from 10 to
213 .init = &stmmac_claim_resource,
215 |-> On ST SoC this calls own "PAD"
216 | manager framework to claim
217 | all the resources necessary
218 | (GPIO ...). The .custom_cfg field
219 | is used to pass a custom config.
222 Below the usage of the stmmac_mdio_bus_data: on this SoC, in fact,
223 there are two MAC cores: one MAC is for MDIO Bus/PHY emulation
224 with fixed_link support.
226 static struct stmmac_mdio_bus_data stmmac1_mdio_bus = {
229 |-> phy device on the bus_id 1
230 .phy_reset = phy_reset;
232 |-> function to provide the phy_reset on this board
236 static struct fixed_phy_status stmmac0_fixed_phy_status = {
242 During the board's device_init we can configure the first
243 MAC for fixed_link by calling:
244 fixed_phy_add(PHY_POLL, 1, &stmmac0_fixed_phy_status));)
245 and the second one, with a real PHY device attached to the bus,
246 by using the stmmac_mdio_bus_data structure (to provide the id, the
247 reset procedure etc).
249 4.10) List of source files:
252 o stmmac_main.c: main network device driver;
253 o stmmac_mdio.c: mdio functions;
254 o stmmac_ethtool.c: ethtool support;
255 o stmmac_timer.[ch]: timer code used for mitigating the driver dma interrupts
256 Only tested on ST40 platforms based.
257 o stmmac.h: private driver structure;
258 o common.h: common definitions and VFTs;
259 o descs.h: descriptor structure definitions;
260 o dwmac1000_core.c: GMAC core functions;
261 o dwmac1000_dma.c: dma functions for the GMAC chip;
262 o dwmac1000.h: specific header file for the GMAC;
263 o dwmac100_core: MAC 100 core and dma code;
264 o dwmac100_dma.c: dma funtions for the MAC chip;
265 o dwmac1000.h: specific header file for the MAC;
266 o dwmac_lib.c: generic DMA functions shared among chips
267 o enh_desc.c: functions for handling enhanced descriptors
268 o norm_desc.c: functions for handling normal descriptors
272 The driver exports many information i.e. internal statistics,
273 debug information, MAC and DMA registers etc.
275 These can be read in several ways depending on the
276 type of the information actually needed.
278 For example a user can be use the ethtool support
279 to get statistics: e.g. using: ethtool -S ethX
280 (that shows the Management counters (MMC) if supported)
281 or sees the MAC/DMA registers: e.g. using: ethtool -d ethX
283 Compiling the Kernel with CONFIG_DEBUG_FS and enabling the
284 STMMAC_DEBUG_FS option the driver will export the following
287 /sys/kernel/debug/stmmaceth/descriptors_status
288 To show the DMA TX/RX descriptor rings
290 Developer can also use the "debug" module parameter to get
291 further debug information.
293 In the end, there are other macros (that cannot be enabled
294 via menuconfig) to turn-on the RX/TX DMA debugging,
295 specific MAC core debug printk etc. Others to enable the
296 debug in the TX and RX processes.
297 All these are only useful during the developing stage
298 and should never enabled inside the code for general usage.
299 In fact, these can generate an huge amount of debug messages.
302 o XGMAC is not supported.
303 o Add the EEE - Energy Efficient Ethernet
304 o Add the PTP - precision time protocol