]>
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 | |
7 | (Synopsys IP blocks); it has been fully tested on STLinux platforms. | |
8 | ||
9 | Currently this network device driver is for all STM embedded MAC/GMAC | |
557e2a39 | 10 | (i.e. 7xxx/5xxx SoCs) and it's known working on other platforms i.e. ARM SPEAr. |
a1d6f3f6 GC |
11 | |
12 | DWC Ether MAC 10/100/1000 Universal version 3.41a and DWC Ether MAC 10/100 | |
13 | Universal version 4.0 have been used for developing the first code | |
14 | implementation. | |
15 | ||
16 | Please, for more information also visit: www.stlinux.com | |
17 | ||
18 | 1) Kernel Configuration | |
19 | The kernel configuration option is STMMAC_ETH: | |
20 | Device Drivers ---> Network device support ---> Ethernet (1000 Mbit) ---> | |
21 | STMicroelectronics 10/100/1000 Ethernet driver (STMMAC_ETH) | |
22 | ||
23 | 2) Driver parameters list: | |
24 | debug: message level (0: no output, 16: all); | |
25 | phyaddr: to manually provide the physical address to the PHY device; | |
26 | dma_rxsize: DMA rx ring size; | |
27 | dma_txsize: DMA tx ring size; | |
28 | buf_sz: DMA buffer size; | |
29 | tc: control the HW FIFO threshold; | |
30 | tx_coe: Enable/Disable Tx Checksum Offload engine; | |
31 | watchdog: transmit timeout (in milliseconds); | |
32 | flow_ctrl: Flow control ability [on/off]; | |
33 | pause: Flow Control Pause Time; | |
34 | tmrate: timer period (only if timer optimisation is configured). | |
35 | ||
36 | 3) Command line options | |
37 | Driver parameters can be also passed in command line by using: | |
38 | stmmaceth=dma_rxsize:128,dma_txsize:512 | |
39 | ||
40 | 4) Driver information and notes | |
41 | ||
42 | 4.1) Transmit process | |
43 | The xmit method is invoked when the kernel needs to transmit a packet; it sets | |
44 | the descriptors in the ring and informs the DMA engine that there is a packet | |
45 | ready to be transmitted. | |
46 | Once the controller has finished transmitting the packet, an interrupt is | |
47 | triggered; So the driver will be able to release the socket buffers. | |
48 | By default, the driver sets the NETIF_F_SG bit in the features field of the | |
49 | net_device structure enabling the scatter/gather feature. | |
50 | ||
51 | 4.2) Receive process | |
52 | When one or more packets are received, an interrupt happens. The interrupts | |
53 | are not queued so the driver has to scan all the descriptors in the ring during | |
54 | the receive process. | |
55 | This is based on NAPI so the interrupt handler signals only if there is work to be | |
56 | done, and it exits. | |
57 | Then the poll method will be scheduled at some future point. | |
58 | The incoming packets are stored, by the DMA, in a list of pre-allocated socket | |
59 | buffers in order to avoid the memcpy (Zero-copy). | |
60 | ||
61 | 4.3) Timer-Driver Interrupt | |
62 | Instead of having the device that asynchronously notifies the frame receptions, the | |
63 | driver configures a timer to generate an interrupt at regular intervals. | |
64 | Based on the granularity of the timer, the frames that are received by the device | |
65 | will experience different levels of latency. Some NICs have dedicated timer | |
66 | device to perform this task. STMMAC can use either the RTC device or the TMU | |
67 | channel 2 on STLinux platforms. | |
68 | The timers frequency can be passed to the driver as parameter; when change it, | |
69 | take care of both hardware capability and network stability/performance impact. | |
70 | Several performance tests on STM platforms showed this optimisation allows to spare | |
71 | the CPU while having the maximum throughput. | |
72 | ||
73 | 4.4) WOL | |
557e2a39 | 74 | Wake up on Lan feature through Magic and Unicast frames are supported for the GMAC |
a1d6f3f6 GC |
75 | core. |
76 | ||
77 | 4.5) DMA descriptors | |
78 | Driver handles both normal and enhanced descriptors. The latter has been only | |
79 | tested on DWC Ether MAC 10/100/1000 Universal version 3.41a. | |
80 | ||
81 | 4.6) Ethtool support | |
82 | Ethtool is supported. Driver statistics and internal errors can be taken using: | |
83 | ethtool -S ethX command. It is possible to dump registers etc. | |
84 | ||
85 | 4.7) Jumbo and Segmentation Offloading | |
86 | Jumbo frames are supported and tested for the GMAC. | |
87 | The GSO has been also added but it's performed in software. | |
88 | LRO is not supported. | |
89 | ||
90 | 4.8) Physical | |
91 | The driver is compatible with PAL to work with PHY and GPHY devices. | |
92 | ||
93 | 4.9) Platform information | |
557e2a39 GC |
94 | Several driver's information can be passed through the platform |
95 | These are included in the include/linux/stmmac.h header file | |
96 | and detailed below as well: | |
a1d6f3f6 | 97 | |
557e2a39 | 98 | struct plat_stmmacenet_data { |
f5539b5b | 99 | int bus_id; |
557e2a39 GC |
100 | int phy_addr; |
101 | int interface; | |
102 | struct stmmac_mdio_bus_data *mdio_bus_data; | |
f5539b5b GC |
103 | int pbl; |
104 | int clk_csr; | |
105 | int has_gmac; | |
106 | int enh_desc; | |
107 | int tx_coe; | |
108 | int bugged_jumbo; | |
109 | int pmt; | |
557e2a39 GC |
110 | int force_sf_dma_mode; |
111 | void (*fix_mac_speed)(void *priv, unsigned int speed); | |
112 | void (*bus_setup)(void __iomem *ioaddr); | |
113 | int (*init)(struct platform_device *pdev); | |
114 | void (*exit)(struct platform_device *pdev); | |
115 | void *bsp_priv; | |
116 | }; | |
a1d6f3f6 GC |
117 | |
118 | Where: | |
557e2a39 GC |
119 | o bus_id: bus identifier. |
120 | o phy_addr: the physical address can be passed from the platform. | |
121 | If it is set to -1 the driver will automatically | |
122 | detect it at run-time by probing all the 32 addresses. | |
123 | o interface: PHY device's interface. | |
124 | o mdio_bus_data: specific platform fields for the MDIO bus. | |
125 | o pbl: the Programmable Burst Length is maximum number of beats to | |
126 | be transferred in one DMA transaction. | |
127 | GMAC also enables the 4xPBL by default. | |
128 | o clk_csr: CSR Clock range selection. | |
129 | o has_gmac: uses the GMAC core. | |
130 | o enh_desc: if sets the MAC will use the enhanced descriptor structure. | |
131 | o tx_coe: core is able to perform the tx csum in HW. | |
132 | o bugged_jumbo: some HWs are not able to perform the csum in HW for | |
133 | over-sized frames due to limited buffer sizes. | |
134 | Setting this flag the csum will be done in SW on | |
135 | JUMBO frames. | |
136 | o pmt: core has the embedded power module (optional). | |
137 | o force_sf_dma_mode: force DMA to use the Store and Forward mode | |
138 | instead of the Threshold. | |
139 | o fix_mac_speed: this callback is used for modifying some syscfg registers | |
140 | (on ST SoCs) according to the link speed negotiated by the | |
141 | physical layer . | |
142 | o bus_setup: perform HW setup of the bus. For example, on some ST platforms | |
143 | this field is used to configure the AMBA bridge to generate more | |
144 | efficient STBus traffic. | |
145 | o init/exit: callbacks used for calling a custom initialisation; | |
146 | this is sometime necessary on some platforms (e.g. ST boxes) | |
147 | where the HW needs to have set some PIO lines or system cfg | |
148 | registers. | |
149 | o custom_cfg: this is a custom configuration that can be passed while | |
150 | initialising the resources. | |
151 | ||
152 | The we have: | |
153 | ||
154 | struct stmmac_mdio_bus_data { | |
155 | int bus_id; | |
156 | int (*phy_reset)(void *priv); | |
157 | unsigned int phy_mask; | |
158 | int *irqs; | |
159 | int probed_phy_irq; | |
160 | }; | |
a1d6f3f6 GC |
161 | |
162 | Where: | |
557e2a39 GC |
163 | o bus_id: bus identifier; |
164 | o phy_reset: hook to reset the phy device attached to the bus. | |
165 | o phy_mask: phy mask passed when register the MDIO bus within the driver. | |
166 | o irqs: list of IRQs, one per PHY. | |
167 | o probed_phy_irq: if irqs is NULL, use this for probed PHY. | |
168 | ||
169 | Below an example how the structures above are using on ST platforms. | |
170 | ||
171 | static struct plat_stmmacenet_data stxYYY_ethernet_platform_data = { | |
172 | .pbl = 32, | |
173 | .has_gmac = 0, | |
174 | .enh_desc = 0, | |
175 | .fix_mac_speed = stxYYY_ethernet_fix_mac_speed, | |
176 | | | |
177 | |-> to write an internal syscfg | |
178 | | on this platform when the | |
179 | | link speed changes from 10 to | |
180 | | 100 and viceversa | |
181 | .init = &stmmac_claim_resource, | |
182 | | | |
183 | |-> On ST SoC this calls own "PAD" | |
184 | | manager framework to claim | |
185 | | all the resources necessary | |
186 | | (GPIO ...). The .custom_cfg field | |
187 | | is used to pass a custom config. | |
188 | }; | |
189 | ||
190 | Below the usage of the stmmac_mdio_bus_data: on this SoC, in fact, | |
191 | there are two MAC cores: one MAC is for MDIO Bus/PHY emulation | |
192 | with fixed_link support. | |
193 | ||
194 | static struct stmmac_mdio_bus_data stmmac1_mdio_bus = { | |
195 | .bus_id = 1, | |
196 | | | |
197 | |-> phy device on the bus_id 1 | |
198 | .phy_reset = phy_reset; | |
199 | | | |
200 | |-> function to provide the phy_reset on this board | |
201 | .phy_mask = 0, | |
202 | }; | |
203 | ||
204 | static struct fixed_phy_status stmmac0_fixed_phy_status = { | |
205 | .link = 1, | |
206 | .speed = 100, | |
207 | .duplex = 1, | |
208 | }; | |
209 | ||
210 | During the board's device_init we can configure the first | |
211 | MAC for fixed_link by calling: | |
212 | fixed_phy_add(PHY_POLL, 1, &stmmac0_fixed_phy_status));) | |
213 | and the second one, with a real PHY device attached to the bus, | |
214 | by using the stmmac_mdio_bus_data structure (to provide the id, the | |
215 | reset procedure etc). | |
216 | ||
217 | 4.10) List of source files: | |
218 | o Kconfig | |
219 | o Makefile | |
220 | o stmmac_main.c: main network device driver; | |
221 | o stmmac_mdio.c: mdio functions; | |
222 | o stmmac_ethtool.c: ethtool support; | |
223 | o stmmac_timer.[ch]: timer code used for mitigating the driver dma interrupts | |
224 | Only tested on ST40 platforms based. | |
225 | o stmmac.h: private driver structure; | |
226 | o common.h: common definitions and VFTs; | |
227 | o descs.h: descriptor structure definitions; | |
228 | o dwmac1000_core.c: GMAC core functions; | |
229 | o dwmac1000_dma.c: dma functions for the GMAC chip; | |
230 | o dwmac1000.h: specific header file for the GMAC; | |
231 | o dwmac100_core: MAC 100 core and dma code; | |
232 | o dwmac100_dma.c: dma funtions for the MAC chip; | |
233 | o dwmac1000.h: specific header file for the MAC; | |
234 | o dwmac_lib.c: generic DMA functions shared among chips | |
235 | o enh_desc.c: functions for handling enhanced descriptors | |
236 | o norm_desc.c: functions for handling normal descriptors | |
237 | ||
238 | 5) TODO: | |
239 | o XGMAC is not supported. | |
240 | o Review the timer optimisation code to use an embedded device that will be | |
a1d6f3f6 | 241 | available in new chip generations. |