]>
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 | |
10 | (7xxx SoCs). | |
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 | |
74 | Wake up on Lan feature through Magic Frame is only supported for the GMAC | |
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 | |
94 | Several information came from the platform; please refer to the | |
95 | driver's Header file in include/linux directory. | |
96 | ||
97 | struct plat_stmmacenet_data { | |
98 | int bus_id; | |
99 | int pbl; | |
100 | int has_gmac; | |
101 | void (*fix_mac_speed)(void *priv, unsigned int speed); | |
102 | void (*bus_setup)(unsigned long ioaddr); | |
103 | #ifdef CONFIG_STM_DRIVERS | |
104 | struct stm_pad_config *pad_config; | |
105 | #endif | |
106 | void *bsp_priv; | |
107 | }; | |
108 | ||
109 | Where: | |
110 | - pbl (Programmable Burst Length) is maximum number of | |
111 | beats to be transferred in one DMA transaction. | |
112 | GMAC also enables the 4xPBL by default. | |
113 | - fix_mac_speed and bus_setup are used to configure internal target | |
114 | registers (on STM platforms); | |
115 | - has_gmac: GMAC core is on board (get it at run-time in the next step); | |
116 | - bus_id: bus identifier. | |
117 | ||
118 | struct plat_stmmacphy_data { | |
119 | int bus_id; | |
120 | int phy_addr; | |
121 | unsigned int phy_mask; | |
122 | int interface; | |
123 | int (*phy_reset)(void *priv); | |
124 | void *priv; | |
125 | }; | |
126 | ||
127 | Where: | |
128 | - bus_id: bus identifier; | |
129 | - phy_addr: physical address used for the attached phy device; | |
130 | set it to -1 to get it at run-time; | |
131 | - interface: physical MII interface mode; | |
132 | - phy_reset: hook to reset HW function. | |
133 | ||
134 | TODO: | |
135 | - Continue to make the driver more generic and suitable for other Synopsys | |
136 | Ethernet controllers used on other architectures (i.e. ARM). | |
137 | - 10G controllers are not supported. | |
138 | - MAC uses Normal descriptors and GMAC uses enhanced ones. | |
139 | This is a limit that should be reviewed. MAC could want to | |
140 | use the enhanced structure. | |
141 | - Checksumming: Rx/Tx csum is done in HW in case of GMAC only. | |
142 | - Review the timer optimisation code to use an embedded device that seems to be | |
143 | available in new chip generations. |