Blame view
Documentation/networking/stmmac.txt
15 KB
a1d6f3f65 stmmac: add docum... |
1 |
STMicroelectronics 10/100/1000 Synopsys Ethernet driver |
0b7a43d37 Documentation: ne... |
2 |
Copyright (C) 2007-2015 STMicroelectronics Ltd |
a1d6f3f65 stmmac: add docum... |
3 4 5 |
Author: Giuseppe Cavallaro <peppe.cavallaro@st.com> This is the driver for the MAC 10/100/1000 on-chip Ethernet controllers |
5b9932685 stmmac: update th... |
6 |
(Synopsys IP blocks). |
a1d6f3f65 stmmac: add docum... |
7 |
|
233b36cf1 stmmac: update dr... |
8 |
Currently this network device driver is for all STi embedded MAC/GMAC |
5b9932685 stmmac: update th... |
9 10 |
(i.e. 7xxx/5xxx SoCs), SPEAr (arm), Loongson1B (mips) and XLINX XC2V3000 FF1152AMT0221 D1215994A VIRTEX FPGA board. |
a1d6f3f65 stmmac: add docum... |
11 |
|
49cfbf675 stmmac: review dr... |
12 |
DWC Ether MAC 10/100/1000 Universal version 3.70a (and older) and DWC Ether |
3d2377144 stmmac: update dr... |
13 |
MAC 10/100 Universal version 4.0 have been used for developing this driver. |
5b9932685 stmmac: update th... |
14 15 |
This driver supports both the platform bus and PCI. |
a1d6f3f65 stmmac: add docum... |
16 17 18 19 20 21 22 |
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) |
233b36cf1 stmmac: update dr... |
23 24 |
CONFIG_STMMAC_PLATFORM: is to enable the platform driver. CONFIG_STMMAC_PCI: is to enable the pci driver. |
a1d6f3f65 stmmac: add docum... |
25 26 27 28 29 30 31 |
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; |
a1d6f3f65 stmmac: add docum... |
32 33 34 |
watchdog: transmit timeout (in milliseconds); flow_ctrl: Flow control ability [on/off]; pause: Flow Control Pause Time; |
49cfbf675 stmmac: review dr... |
35 36 |
eee_timer: tx EEE timer; chain_mode: select chain mode instead of ring. |
a1d6f3f65 stmmac: add docum... |
37 38 39 40 41 42 43 44 45 46 47 |
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. |
a1d6f3f65 stmmac: add docum... |
48 |
By default, the driver sets the NETIF_F_SG bit in the features field of the |
233b36cf1 stmmac: update dr... |
49 50 51 52 |
net_device structure enabling the scatter-gather feature. This is true on chips and configurations where the checksum can be done in hardware. Once the controller has finished transmitting the packet, napi will be scheduled to release the transmit resources. |
a1d6f3f65 stmmac: add docum... |
53 54 55 56 57 |
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. |
3d2377144 stmmac: update dr... |
58 59 |
This is based on NAPI so the interrupt handler signals only if there is work to be done, and it exits. |
a1d6f3f65 stmmac: add docum... |
60 61 |
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 |
233b36cf1 stmmac: update dr... |
62 |
buffers in order to avoid the memcpy (zero-copy). |
a1d6f3f65 stmmac: add docum... |
63 |
|
f9e01b556 stmmac: update th... |
64 65 66 67 |
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. |
f9e01b556 stmmac: update th... |
68 |
Mitigation parameters can be tuned by ethtool. |
a1d6f3f65 stmmac: add docum... |
69 70 |
4.4) WOL |
3d2377144 stmmac: update dr... |
71 72 |
Wake up on Lan feature through Magic and Unicast frames are supported for the GMAC core. |
a1d6f3f65 stmmac: add docum... |
73 74 |
4.5) DMA descriptors |
233b36cf1 stmmac: update dr... |
75 |
Driver handles both normal and alternate descriptors. The latter has been only |
51e3137b9 stmmac: update th... |
76 77 78 79 80 81 82 83 84 85 |
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. |
a1d6f3f65 stmmac: add docum... |
86 |
|
233b36cf1 stmmac: update dr... |
87 88 89 90 91 92 93 |
4.5.1) Extended descriptors The extended descriptors give us information about the 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 are used for saving the hardware timestamps and Extended Status. |
a1d6f3f65 stmmac: add docum... |
94 |
4.6) Ethtool support |
233b36cf1 stmmac: update dr... |
95 96 97 98 99 |
Ethtool is supported. For example, driver statistics (including RMON), internal errors can be taken using: # ethtool -S ethX command |
a1d6f3f65 stmmac: add docum... |
100 101 102 103 104 105 106 |
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 |
233b36cf1 stmmac: update dr... |
107 108 |
The driver is compatible with Physical Abstraction Layer to be connected with PHY and GPHY devices. |
a1d6f3f65 stmmac: add docum... |
109 110 |
4.9) Platform information |
233b36cf1 stmmac: update dr... |
111 |
Several information can be passed through the platform and device-tree. |
a1d6f3f65 stmmac: add docum... |
112 |
|
3d2377144 stmmac: update dr... |
113 114 |
struct plat_stmmacenet_data { char *phy_bus_name; |
f5539b5bf stmmac: update th... |
115 |
int bus_id; |
557e2a394 stmmac: improve a... |
116 117 118 |
int phy_addr; int interface; struct stmmac_mdio_bus_data *mdio_bus_data; |
8327eb65e stmmac: re-work t... |
119 |
struct stmmac_dma_cfg *dma_cfg; |
f5539b5bf stmmac: update th... |
120 121 122 123 |
int clk_csr; int has_gmac; int enh_desc; int tx_coe; |
55f9a4d6f stmmac: Define CS... |
124 |
int rx_coe; |
f5539b5bf stmmac: update th... |
125 126 |
int bugged_jumbo; int pmt; |
557e2a394 stmmac: improve a... |
127 |
int force_sf_dma_mode; |
e2a240c7d driver:net:stmmac... |
128 |
int force_thresh_dma_mode; |
f9e01b556 stmmac: update th... |
129 |
int riwt_off; |
233b36cf1 stmmac: update dr... |
130 131 |
int max_speed; int maxmtu; |
557e2a394 stmmac: improve a... |
132 133 |
void (*fix_mac_speed)(void *priv, unsigned int speed); void (*bus_setup)(void __iomem *ioaddr); |
938dfdaa3 net: stmmac: Allo... |
134 135 |
int (*init)(struct platform_device *pdev, void *priv); void (*exit)(struct platform_device *pdev, void *priv); |
557e2a394 stmmac: improve a... |
136 |
void *bsp_priv; |
0b7a43d37 Documentation: ne... |
137 138 |
int has_gmac4; bool tso_en; |
233b36cf1 stmmac: update dr... |
139 |
}; |
a1d6f3f65 stmmac: add docum... |
140 141 |
Where: |
3d2377144 stmmac: update dr... |
142 |
o phy_bus_name: phy bus name to attach to the stmmac. |
557e2a394 stmmac: improve a... |
143 144 145 146 147 148 |
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. |
3d2377144 stmmac: update dr... |
149 150 |
o dma_cfg: internal DMA parameters o pbl: the Programmable Burst Length is maximum number of beats to |
557e2a394 stmmac: improve a... |
151 152 |
be transferred in one DMA transaction. GMAC also enables the 4xPBL by default. |
3d2377144 stmmac: update dr... |
153 |
o fixed_burst/mixed_burst/burst_len |
cd7201f47 stmmac: MDC clock... |
154 |
o clk_csr: fixed CSR Clock range selection. |
557e2a394 stmmac: improve a... |
155 156 157 |
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. |
55f9a4d6f stmmac: Define CS... |
158 159 |
o rx_coe: the supports three check sum offloading engine types: type_1, type_2 (full csum) and no RX coe. |
557e2a394 stmmac: improve a... |
160 161 162 163 164 165 166 |
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. |
c17cb8b55 doc:net: Fix typo... |
167 |
o force_thresh_dma_mode: force DMA to use the Threshold mode other than |
e2a240c7d driver:net:stmmac... |
168 |
the Store and Forward mode. |
f9e01b556 stmmac: update th... |
169 |
o riwt_off: force to disable the RX watchdog feature and switch to NAPI mode. |
557e2a394 stmmac: improve a... |
170 171 172 173 174 175 |
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. |
75fee5955 stmmac: remove se... |
176 |
o init/exit: callbacks used for calling a custom initialization; |
557e2a394 stmmac: improve a... |
177 178 |
this is sometime necessary on some platforms (e.g. ST boxes) where the HW needs to have set some PIO lines or system cfg |
75fee5955 stmmac: remove se... |
179 |
registers. init/exit callbacks should not use or modify |
938dfdaa3 net: stmmac: Allo... |
180 |
platform data. |
c17cb8b55 doc:net: Fix typo... |
181 |
o bsp_priv: another private pointer. |
0b7a43d37 Documentation: ne... |
182 183 |
o has_gmac4: uses GMAC4 core. o tso_en: Enables TSO (TCP Segmentation Offload) feature. |
557e2a394 stmmac: improve a... |
184 |
|
8327eb65e stmmac: re-work t... |
185 |
For MDIO bus The we have: |
557e2a394 stmmac: improve a... |
186 187 |
struct stmmac_mdio_bus_data { |
557e2a394 stmmac: improve a... |
188 189 190 191 192 |
int (*phy_reset)(void *priv); unsigned int phy_mask; int *irqs; int probed_phy_irq; }; |
a1d6f3f65 stmmac: add docum... |
193 194 |
Where: |
557e2a394 stmmac: improve a... |
195 196 197 198 |
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. |
8327eb65e stmmac: re-work t... |
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 |
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. --- |
557e2a394 stmmac: improve a... |
216 217 218 |
Below an example how the structures above are using on ST platforms. static struct plat_stmmacenet_data stxYYY_ethernet_platform_data = { |
557e2a394 stmmac: improve a... |
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 |
.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 = { |
557e2a394 stmmac: improve a... |
241 242 243 244 245 246 247 248 249 250 251 252 253 254 |
.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: |
a5597008d phy: fixed_phy: A... |
255 |
fixed_phy_add(PHY_POLL, 1, &stmmac0_fixed_phy_status, -1); |
557e2a394 stmmac: improve a... |
256 257 258 |
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). |
233b36cf1 stmmac: update dr... |
259 260 261 262 263 264 265 266 267 268 |
Note that, starting from new chips, where it is available the HW capability register, many configurations are discovered at run-time for example to understand if EEE, HW csum, PTP, enhanced descriptor etc are actually available. As strategy adopted in this driver, the information from the HW capability register can replace what has been passed from the platform. 4.10) Device-tree support. Please see the following document: Documentation/devicetree/bindings/net/stmmac.txt |
233b36cf1 stmmac: update dr... |
269 270 271 272 273 274 |
4.11) This is a summary of the content of some relevant files: o stmmac_main.c: to implement the main network device driver; o stmmac_mdio.c: to provide mdio functions; o stmmac_pci: this the PCI driver; o stmmac_platform.c: this the platform driver (OF supported) o stmmac_ethtool.c: to implement the ethtool support; |
557e2a394 stmmac: improve a... |
275 276 |
o stmmac.h: private driver structure; o common.h: common definitions and VFTs; |
0b7a43d37 Documentation: ne... |
277 278 279 |
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; |
70523e639 drivers: net: stm... |
280 |
o stmmac_pcs.h: Physical Coding Sublayer common implementation; |
0b7a43d37 Documentation: ne... |
281 282 283 284 |
o dwmac-<XXX>.c: these are for the platform glue-logic file; e.g. dwmac-sti.c for STMicroelectronics SoCs. - GMAC 3.x |
557e2a394 stmmac: improve a... |
285 |
o descs.h: descriptor structure definitions; |
233b36cf1 stmmac: update dr... |
286 287 288 289 290 |
o dwmac1000_core.c: dwmac GiGa core functions; o dwmac1000_dma.c: dma functions for the GMAC chip; o dwmac1000.h: specific header file for the dwmac GiGa; o dwmac100_core: dwmac 100 core code; o dwmac100_dma.c: dma functions for the dwmac 100 chip; |
557e2a394 stmmac: improve a... |
291 |
o dwmac1000.h: specific header file for the MAC; |
233b36cf1 stmmac: update dr... |
292 |
o dwmac_lib.c: generic DMA functions; |
0ec2ccd08 stmmac: update th... |
293 294 295 |
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; |
0b7a43d37 Documentation: ne... |
296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 |
- GMAC4.x generation o dwmac4_core.c: dwmac GMAC4.x core functions; o dwmac4_desc.c: functions for handling GMAC4.x descriptors; o dwmac4_descs.h: descriptor definitions; o dwmac4_dma.c: dma functions for the GMAC4.x chip; o dwmac4_dma.h: dma definitions for the GMAC4.x chip; o dwmac4.h: core definitions for the GMAC4.x chip; o dwmac4_lib.c: generic GMAC4.x functions; 4.12) TSO support (GMAC4.x) TSO (Tcp Segmentation Offload) feature is supported by GMAC 4.x chip family. When a packet is sent through TCP protocol, the TCP stack ensures that the SKB provided to the low level driver (stmmac in our case) matches with the maximum frame len (IP header + TCP header + payload <= 1500 bytes (for MTU set to 1500)). It means that if an application using TCP want to send a packet which will have a length (after adding headers) > 1514 the packet will be split in several TCP packets: The data payload is split and headers (TCP/IP ..) are added. It is done by software. When TSO is enabled, the TCP stack doesn't care about the maximum frame length and provide SKB packet to stmmac as it is. The GMAC IP will have to perform the segmentation by it self to match with maximum frame length. This feature can be enabled in device tree through "snps,tso" entry. |
557e2a394 stmmac: improve a... |
322 |
|
4f2f25f9f stmmac: update th... |
323 324 325 326 327 328 329 330 331 332 333 334 |
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 |
233b36cf1 stmmac: update dr... |
335 |
Compiling the Kernel with CONFIG_DEBUG_FS the driver will export the following |
4f2f25f9f stmmac: update th... |
336 337 338 339 |
debugfs entries: /sys/kernel/debug/stmmaceth/descriptors_status To show the DMA TX/RX descriptor rings |
233b36cf1 stmmac: update dr... |
340 341 |
Developer can also use the "debug" module parameter to get further debug information (please see: NETIF Msg Level). |
4f2f25f9f stmmac: update th... |
342 |
|
0ec2ccd08 stmmac: update th... |
343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 |
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. |
233b36cf1 stmmac: update dr... |
363 |
7) Precision Time Protocol (PTP) |
94fbbbf89 stmmac: update th... |
364 365 366 367 368 369 370 371 |
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. |
233b36cf1 stmmac: update dr... |
372 |
8) SGMII/RGMII supports |
94fbbbf89 stmmac: update th... |
373 374 375 376 377 378 379 380 |
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. |