]>
Commit | Line | Data |
---|---|---|
a1d6f3f6 GC |
1 | STMicroelectronics 10/100/1000 Synopsys Ethernet driver |
2 | ||
3 | Copyright (C) 2007-2010 STMicroelectronics Ltd | |
4 | Author: Giuseppe Cavallaro <peppe.cavallaro@st.com> | |
5 | ||
6 | This is the driver for the MAC 10/100/1000 on-chip Ethernet controllers | |
5b993268 | 7 | (Synopsys IP blocks). |
a1d6f3f6 GC |
8 | |
9 | Currently this network device driver is for all STM embedded MAC/GMAC | |
5b993268 GC |
10 | (i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XLINX XC2V3000 |
11 | FF1152AMT0221 D1215994A VIRTEX FPGA board. | |
a1d6f3f6 | 12 | |
3d237714 GC |
13 | DWC Ether MAC 10/100/1000 Universal version 3.60a (and older) and DWC Ether |
14 | MAC 10/100 Universal version 4.0 have been used for developing this driver. | |
5b993268 GC |
15 | |
16 | This driver supports both the platform bus and PCI. | |
a1d6f3f6 GC |
17 | |
18 | Please, for more information also visit: www.stlinux.com | |
19 | ||
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) | |
24 | ||
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). | |
37 | ||
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 | |
41 | ||
42 | 4) Driver information and notes | |
43 | ||
44 | 4.1) Transmit process | |
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. | |
52 | ||
53 | 4.2) Receive process | |
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 | |
56 | the receive process. | |
3d237714 GC |
57 | This is based on NAPI so the interrupt handler signals only if there is work |
58 | to be done, and it exits. | |
a1d6f3f6 GC |
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). | |
62 | ||
63 | 4.3) Timer-Driver Interrupt | |
3d237714 GC |
64 | Instead of having the device that asynchronously notifies the frame receptions, |
65 | the 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 | |
67 | device will experience different levels of latency. Some NICs have dedicated | |
68 | timer device to perform this task. STMMAC can use either the RTC device or the | |
69 | TMU channel 2 on STLinux platforms. | |
a1d6f3f6 GC |
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. | |
3d237714 GC |
72 | Several performance tests on STM platforms showed this optimisation allows to |
73 | spare the CPU while having the maximum throughput. | |
a1d6f3f6 GC |
74 | |
75 | 4.4) WOL | |
3d237714 GC |
76 | Wake up on Lan feature through Magic and Unicast frames are supported for the |
77 | GMAC core. | |
a1d6f3f6 GC |
78 | |
79 | 4.5) DMA descriptors | |
80 | Driver handles both normal and enhanced descriptors. The latter has been only | |
51e3137b GC |
81 | tested on DWC Ether MAC 10/100/1000 Universal version 3.41a and later. |
82 | ||
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. | |
87 | ||
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. | |
a1d6f3f6 GC |
91 | |
92 | 4.6) Ethtool support | |
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. | |
95 | ||
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. | |
99 | LRO is not supported. | |
100 | ||
101 | 4.8) Physical | |
102 | The driver is compatible with PAL to work with PHY and GPHY devices. | |
103 | ||
104 | 4.9) Platform information | |
557e2a39 GC |
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: | |
a1d6f3f6 | 108 | |
3d237714 GC |
109 | struct plat_stmmacenet_data { |
110 | char *phy_bus_name; | |
f5539b5b | 111 | int bus_id; |
557e2a39 GC |
112 | int phy_addr; |
113 | int interface; | |
114 | struct stmmac_mdio_bus_data *mdio_bus_data; | |
8327eb65 | 115 | struct stmmac_dma_cfg *dma_cfg; |
f5539b5b GC |
116 | int clk_csr; |
117 | int has_gmac; | |
118 | int enh_desc; | |
119 | int tx_coe; | |
55f9a4d6 | 120 | int rx_coe; |
f5539b5b GC |
121 | int bugged_jumbo; |
122 | int pmt; | |
557e2a39 GC |
123 | int force_sf_dma_mode; |
124 | void (*fix_mac_speed)(void *priv, unsigned int speed); | |
125 | void (*bus_setup)(void __iomem *ioaddr); | |
126 | int (*init)(struct platform_device *pdev); | |
127 | void (*exit)(struct platform_device *pdev); | |
3d237714 GC |
128 | void *custom_cfg; |
129 | void *custom_data; | |
557e2a39 GC |
130 | void *bsp_priv; |
131 | }; | |
a1d6f3f6 GC |
132 | |
133 | Where: | |
3d237714 | 134 | o phy_bus_name: phy bus name to attach to the stmmac. |
557e2a39 GC |
135 | o bus_id: bus identifier. |
136 | o phy_addr: the physical address can be passed from the platform. | |
137 | If it is set to -1 the driver will automatically | |
138 | detect it at run-time by probing all the 32 addresses. | |
139 | o interface: PHY device's interface. | |
140 | o mdio_bus_data: specific platform fields for the MDIO bus. | |
3d237714 GC |
141 | o dma_cfg: internal DMA parameters |
142 | o pbl: the Programmable Burst Length is maximum number of beats to | |
557e2a39 GC |
143 | be transferred in one DMA transaction. |
144 | GMAC also enables the 4xPBL by default. | |
3d237714 | 145 | o fixed_burst/mixed_burst/burst_len |
cd7201f4 | 146 | o clk_csr: fixed CSR Clock range selection. |
557e2a39 GC |
147 | o has_gmac: uses the GMAC core. |
148 | o enh_desc: if sets the MAC will use the enhanced descriptor structure. | |
149 | o tx_coe: core is able to perform the tx csum in HW. | |
55f9a4d6 DS |
150 | o rx_coe: the supports three check sum offloading engine types: |
151 | type_1, type_2 (full csum) and no RX coe. | |
557e2a39 GC |
152 | o bugged_jumbo: some HWs are not able to perform the csum in HW for |
153 | over-sized frames due to limited buffer sizes. | |
154 | Setting this flag the csum will be done in SW on | |
155 | JUMBO frames. | |
156 | o pmt: core has the embedded power module (optional). | |
157 | o force_sf_dma_mode: force DMA to use the Store and Forward mode | |
158 | instead of the Threshold. | |
159 | o fix_mac_speed: this callback is used for modifying some syscfg registers | |
160 | (on ST SoCs) according to the link speed negotiated by the | |
161 | physical layer . | |
162 | o bus_setup: perform HW setup of the bus. For example, on some ST platforms | |
163 | this field is used to configure the AMBA bridge to generate more | |
164 | efficient STBus traffic. | |
165 | o init/exit: callbacks used for calling a custom initialisation; | |
166 | this is sometime necessary on some platforms (e.g. ST boxes) | |
167 | where the HW needs to have set some PIO lines or system cfg | |
168 | registers. | |
3d237714 GC |
169 | o custom_cfg/custom_data: this is a custom configuration that can be passed |
170 | while initialising the resources. | |
171 | o bsp_priv: another private poiter. | |
557e2a39 | 172 | |
8327eb65 | 173 | For MDIO bus The we have: |
557e2a39 GC |
174 | |
175 | struct stmmac_mdio_bus_data { | |
557e2a39 GC |
176 | int (*phy_reset)(void *priv); |
177 | unsigned int phy_mask; | |
178 | int *irqs; | |
179 | int probed_phy_irq; | |
180 | }; | |
a1d6f3f6 GC |
181 | |
182 | Where: | |
557e2a39 GC |
183 | o phy_reset: hook to reset the phy device attached to the bus. |
184 | o phy_mask: phy mask passed when register the MDIO bus within the driver. | |
185 | o irqs: list of IRQs, one per PHY. | |
186 | o probed_phy_irq: if irqs is NULL, use this for probed PHY. | |
187 | ||
8327eb65 DS |
188 | For DMA engine we have the following internal fields that should be |
189 | tuned according to the HW capabilities. | |
190 | ||
191 | struct stmmac_dma_cfg { | |
192 | int pbl; | |
193 | int fixed_burst; | |
194 | int burst_len_supported; | |
195 | }; | |
196 | ||
197 | Where: | |
198 | o pbl: Programmable Burst Length | |
199 | o fixed_burst: program the DMA to use the fixed burst mode | |
200 | o burst_len: this is the value we put in the register | |
201 | supported values are provided as macros in | |
202 | linux/stmmac.h header file. | |
203 | ||
204 | --- | |
205 | ||
557e2a39 GC |
206 | Below an example how the structures above are using on ST platforms. |
207 | ||
208 | static struct plat_stmmacenet_data stxYYY_ethernet_platform_data = { | |
557e2a39 GC |
209 | .has_gmac = 0, |
210 | .enh_desc = 0, | |
211 | .fix_mac_speed = stxYYY_ethernet_fix_mac_speed, | |
212 | | | |
213 | |-> to write an internal syscfg | |
214 | | on this platform when the | |
215 | | link speed changes from 10 to | |
216 | | 100 and viceversa | |
217 | .init = &stmmac_claim_resource, | |
218 | | | |
219 | |-> On ST SoC this calls own "PAD" | |
220 | | manager framework to claim | |
221 | | all the resources necessary | |
222 | | (GPIO ...). The .custom_cfg field | |
223 | | is used to pass a custom config. | |
224 | }; | |
225 | ||
226 | Below the usage of the stmmac_mdio_bus_data: on this SoC, in fact, | |
227 | there are two MAC cores: one MAC is for MDIO Bus/PHY emulation | |
228 | with fixed_link support. | |
229 | ||
230 | static struct stmmac_mdio_bus_data stmmac1_mdio_bus = { | |
557e2a39 GC |
231 | .phy_reset = phy_reset; |
232 | | | |
233 | |-> function to provide the phy_reset on this board | |
234 | .phy_mask = 0, | |
235 | }; | |
236 | ||
237 | static struct fixed_phy_status stmmac0_fixed_phy_status = { | |
238 | .link = 1, | |
239 | .speed = 100, | |
240 | .duplex = 1, | |
241 | }; | |
242 | ||
243 | During the board's device_init we can configure the first | |
244 | MAC for fixed_link by calling: | |
245 | fixed_phy_add(PHY_POLL, 1, &stmmac0_fixed_phy_status));) | |
246 | and the second one, with a real PHY device attached to the bus, | |
247 | by using the stmmac_mdio_bus_data structure (to provide the id, the | |
248 | reset procedure etc). | |
249 | ||
250 | 4.10) List of source files: | |
251 | o Kconfig | |
252 | o Makefile | |
253 | o stmmac_main.c: main network device driver; | |
254 | o stmmac_mdio.c: mdio functions; | |
0ec2ccd0 GC |
255 | o stmmac_pci: PCI driver; |
256 | o stmmac_platform.c: platform driver | |
557e2a39 GC |
257 | o stmmac_ethtool.c: ethtool support; |
258 | o stmmac_timer.[ch]: timer code used for mitigating the driver dma interrupts | |
0ec2ccd0 | 259 | (only tested on ST40 platforms based); |
557e2a39 GC |
260 | o stmmac.h: private driver structure; |
261 | o common.h: common definitions and VFTs; | |
262 | o descs.h: descriptor structure definitions; | |
263 | o dwmac1000_core.c: GMAC core functions; | |
264 | o dwmac1000_dma.c: dma functions for the GMAC chip; | |
265 | o dwmac1000.h: specific header file for the GMAC; | |
266 | o dwmac100_core: MAC 100 core and dma code; | |
267 | o dwmac100_dma.c: dma funtions for the MAC chip; | |
268 | o dwmac1000.h: specific header file for the MAC; | |
0ec2ccd0 GC |
269 | o dwmac_lib.c: generic DMA functions shared among chips; |
270 | o enh_desc.c: functions for handling enhanced descriptors; | |
271 | o norm_desc.c: functions for handling normal descriptors; | |
272 | o chain_mode.c/ring_mode.c:: functions to manage RING/CHAINED modes; | |
273 | o mmc_core.c/mmc.h: Management MAC Counters; | |
557e2a39 | 274 | |
4f2f25f9 GC |
275 | 5) Debug Information |
276 | ||
277 | The driver exports many information i.e. internal statistics, | |
278 | debug information, MAC and DMA registers etc. | |
279 | ||
280 | These can be read in several ways depending on the | |
281 | type of the information actually needed. | |
282 | ||
283 | For example a user can be use the ethtool support | |
284 | to get statistics: e.g. using: ethtool -S ethX | |
285 | (that shows the Management counters (MMC) if supported) | |
286 | or sees the MAC/DMA registers: e.g. using: ethtool -d ethX | |
287 | ||
288 | Compiling the Kernel with CONFIG_DEBUG_FS and enabling the | |
289 | STMMAC_DEBUG_FS option the driver will export the following | |
290 | debugfs entries: | |
291 | ||
292 | /sys/kernel/debug/stmmaceth/descriptors_status | |
293 | To show the DMA TX/RX descriptor rings | |
294 | ||
295 | Developer can also use the "debug" module parameter to get | |
296 | further debug information. | |
297 | ||
298 | In the end, there are other macros (that cannot be enabled | |
299 | via menuconfig) to turn-on the RX/TX DMA debugging, | |
300 | specific MAC core debug printk etc. Others to enable the | |
301 | debug in the TX and RX processes. | |
302 | All these are only useful during the developing stage | |
303 | and should never enabled inside the code for general usage. | |
304 | In fact, these can generate an huge amount of debug messages. | |
305 | ||
0ec2ccd0 GC |
306 | 6) Energy Efficient Ethernet |
307 | ||
308 | Energy Efficient Ethernet(EEE) enables IEEE 802.3 MAC sublayer along | |
309 | with a family of Physical layer to operate in the Low power Idle(LPI) | |
310 | mode. The EEE mode supports the IEEE 802.3 MAC operation at 100Mbps, | |
311 | 1000Mbps & 10Gbps. | |
312 | ||
313 | The LPI mode allows power saving by switching off parts of the | |
314 | communication device functionality when there is no data to be | |
315 | transmitted & received. The system on both the side of the link can | |
316 | disable some functionalities & save power during the period of low-link | |
317 | utilization. The MAC controls whether the system should enter or exit | |
318 | the LPI mode & communicate this to PHY. | |
319 | ||
320 | As soon as the interface is opened, the driver verifies if the EEE can | |
321 | be supported. This is done by looking at both the DMA HW capability | |
322 | register and the PHY devices MCD registers. | |
323 | To enter in Tx LPI mode the driver needs to have a software timer | |
324 | that enable and disable the LPI mode when there is nothing to be | |
325 | transmitted. | |
326 | ||
327 | 7) TODO: | |
557e2a39 | 328 | o XGMAC is not supported. |
5b993268 | 329 | o Add the PTP - precision time protocol |