diff options
author | Giuseppe CAVALLARO <peppe.cavallaro@st.com> | 2011-07-19 20:05:24 -0400 |
---|---|---|
committer | David S. Miller <davem@davemloft.net> | 2011-07-21 18:29:16 -0400 |
commit | 557e2a394de0d142ba930ff3cdb2909419414e06 (patch) | |
tree | fbc670fe5840b9c75fbd02518cb984391b80dfa5 | |
parent | 36bcfe7d74782c07f601edc4831f6b1ef40e9e43 (diff) |
stmmac: improve and up-to-date the documentation
This patch adds new information for the driver
especially about its platform structure fields.
Signed-off-by: Giuseppe Cavallaro <peppe.cavallaro@st.com>
Signed-off-by: David S. Miller <davem@davemloft.net>
-rw-r--r-- | Documentation/networking/stmmac.txt | 200 |
1 files changed, 136 insertions, 64 deletions
diff --git a/Documentation/networking/stmmac.txt b/Documentation/networking/stmmac.txt index 80a7a3454902..57a24108b845 100644 --- a/Documentation/networking/stmmac.txt +++ b/Documentation/networking/stmmac.txt | |||
@@ -7,7 +7,7 @@ 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. | 7 | (Synopsys IP blocks); it has been fully tested on STLinux platforms. |
8 | 8 | ||
9 | Currently this network device driver is for all STM embedded MAC/GMAC | 9 | Currently this network device driver is for all STM embedded MAC/GMAC |
10 | (7xxx SoCs). Other platforms start using it i.e. ARM SPEAr. | 10 | (i.e. 7xxx/5xxx SoCs) and it's known working on other platforms i.e. ARM SPEAr. |
11 | 11 | ||
12 | DWC Ether MAC 10/100/1000 Universal version 3.41a and DWC Ether MAC 10/100 | 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 | 13 | Universal version 4.0 have been used for developing the first code |
@@ -71,7 +71,7 @@ Several performance tests on STM platforms showed this optimisation allows to sp | |||
71 | the CPU while having the maximum throughput. | 71 | the CPU while having the maximum throughput. |
72 | 72 | ||
73 | 4.4) WOL | 73 | 4.4) WOL |
74 | Wake up on Lan feature through Magic Frame is only supported for the GMAC | 74 | Wake up on Lan feature through Magic and Unicast frames are supported for the GMAC |
75 | core. | 75 | core. |
76 | 76 | ||
77 | 4.5) DMA descriptors | 77 | 4.5) DMA descriptors |
@@ -91,11 +91,15 @@ LRO is not supported. | |||
91 | The driver is compatible with PAL to work with PHY and GPHY devices. | 91 | The driver is compatible with PAL to work with PHY and GPHY devices. |
92 | 92 | ||
93 | 4.9) Platform information | 93 | 4.9) Platform information |
94 | Several information came from the platform; please refer to the | 94 | Several driver's information can be passed through the platform |
95 | driver's Header file in include/linux directory. | 95 | These are included in the include/linux/stmmac.h header file |
96 | and detailed below as well: | ||
96 | 97 | ||
97 | struct plat_stmmacenet_data { | 98 | struct plat_stmmacenet_data { |
98 | int bus_id; | 99 | int bus_id; |
100 | int phy_addr; | ||
101 | int interface; | ||
102 | struct stmmac_mdio_bus_data *mdio_bus_data; | ||
99 | int pbl; | 103 | int pbl; |
100 | int clk_csr; | 104 | int clk_csr; |
101 | int has_gmac; | 105 | int has_gmac; |
@@ -103,67 +107,135 @@ struct plat_stmmacenet_data { | |||
103 | int tx_coe; | 107 | int tx_coe; |
104 | int bugged_jumbo; | 108 | int bugged_jumbo; |
105 | int pmt; | 109 | int pmt; |
106 | void (*fix_mac_speed)(void *priv, unsigned int speed); | 110 | int force_sf_dma_mode; |
107 | void (*bus_setup)(unsigned long ioaddr); | 111 | void (*fix_mac_speed)(void *priv, unsigned int speed); |
108 | #ifdef CONFIG_STM_DRIVERS | 112 | void (*bus_setup)(void __iomem *ioaddr); |
109 | struct stm_pad_config *pad_config; | 113 | int (*init)(struct platform_device *pdev); |
110 | #endif | 114 | void (*exit)(struct platform_device *pdev); |
111 | void *bsp_priv; | 115 | void *bsp_priv; |
112 | }; | 116 | }; |
113 | 117 | ||
114 | Where: | 118 | Where: |
115 | - pbl (Programmable Burst Length) is maximum number of | 119 | o bus_id: bus identifier. |
116 | beats to be transferred in one DMA transaction. | 120 | o phy_addr: the physical address can be passed from the platform. |
117 | GMAC also enables the 4xPBL by default. | 121 | If it is set to -1 the driver will automatically |
118 | - fix_mac_speed and bus_setup are used to configure internal target | 122 | detect it at run-time by probing all the 32 addresses. |
119 | registers (on STM platforms); | 123 | o interface: PHY device's interface. |
120 | - has_gmac: GMAC core is on board (get it at run-time in the next step); | 124 | o mdio_bus_data: specific platform fields for the MDIO bus. |
121 | - bus_id: bus identifier. | 125 | o pbl: the Programmable Burst Length is maximum number of beats to |
122 | - tx_coe: core is able to perform the tx csum in HW. | 126 | be transferred in one DMA transaction. |
123 | - enh_desc: if sets the MAC will use the enhanced descriptor structure. | 127 | GMAC also enables the 4xPBL by default. |
124 | - clk_csr: CSR Clock range selection. | 128 | o clk_csr: CSR Clock range selection. |
125 | - bugged_jumbo: some HWs are not able to perform the csum in HW for | 129 | o has_gmac: uses the GMAC core. |
126 | over-sized frames due to limited buffer sizes. Setting this | 130 | o enh_desc: if sets the MAC will use the enhanced descriptor structure. |
127 | flag the csum will be done in SW on JUMBO frames. | 131 | o tx_coe: core is able to perform the tx csum in HW. |
128 | 132 | o bugged_jumbo: some HWs are not able to perform the csum in HW for | |
129 | struct plat_stmmacphy_data { | 133 | over-sized frames due to limited buffer sizes. |
130 | int bus_id; | 134 | Setting this flag the csum will be done in SW on |
131 | int phy_addr; | 135 | JUMBO frames. |
132 | unsigned int phy_mask; | 136 | o pmt: core has the embedded power module (optional). |
133 | int interface; | 137 | o force_sf_dma_mode: force DMA to use the Store and Forward mode |
134 | int (*phy_reset)(void *priv); | 138 | instead of the Threshold. |
135 | void *priv; | 139 | o fix_mac_speed: this callback is used for modifying some syscfg registers |
136 | }; | 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 | }; | ||
137 | 161 | ||
138 | Where: | 162 | Where: |
139 | - bus_id: bus identifier; | 163 | o bus_id: bus identifier; |
140 | - phy_addr: physical address used for the attached phy device; | 164 | o phy_reset: hook to reset the phy device attached to the bus. |
141 | set it to -1 to get it at run-time; | 165 | o phy_mask: phy mask passed when register the MDIO bus within the driver. |
142 | - interface: physical MII interface mode; | 166 | o irqs: list of IRQs, one per PHY. |
143 | - phy_reset: hook to reset HW function. | 167 | o probed_phy_irq: if irqs is NULL, use this for probed PHY. |
144 | 168 | ||
145 | SOURCES: | 169 | Below an example how the structures above are using on ST platforms. |
146 | - Kconfig | 170 | |
147 | - Makefile | 171 | static struct plat_stmmacenet_data stxYYY_ethernet_platform_data = { |
148 | - stmmac_main.c: main network device driver; | 172 | .pbl = 32, |
149 | - stmmac_mdio.c: mdio functions; | 173 | .has_gmac = 0, |
150 | - stmmac_ethtool.c: ethtool support; | 174 | .enh_desc = 0, |
151 | - stmmac_timer.[ch]: timer code used for mitigating the driver dma interrupts | 175 | .fix_mac_speed = stxYYY_ethernet_fix_mac_speed, |
152 | Only tested on ST40 platforms based. | 176 | | |
153 | - stmmac.h: private driver structure; | 177 | |-> to write an internal syscfg |
154 | - common.h: common definitions and VFTs; | 178 | | on this platform when the |
155 | - descs.h: descriptor structure definitions; | 179 | | link speed changes from 10 to |
156 | - dwmac1000_core.c: GMAC core functions; | 180 | | 100 and viceversa |
157 | - dwmac1000_dma.c: dma functions for the GMAC chip; | 181 | .init = &stmmac_claim_resource, |
158 | - dwmac1000.h: specific header file for the GMAC; | 182 | | |
159 | - dwmac100_core: MAC 100 core and dma code; | 183 | |-> On ST SoC this calls own "PAD" |
160 | - dwmac100_dma.c: dma funtions for the MAC chip; | 184 | | manager framework to claim |
161 | - dwmac1000.h: specific header file for the MAC; | 185 | | all the resources necessary |
162 | - dwmac_lib.c: generic DMA functions shared among chips | 186 | | (GPIO ...). The .custom_cfg field |
163 | - enh_desc.c: functions for handling enhanced descriptors | 187 | | is used to pass a custom config. |
164 | - norm_desc.c: functions for handling normal descriptors | 188 | }; |
165 | 189 | ||
166 | TODO: | 190 | Below the usage of the stmmac_mdio_bus_data: on this SoC, in fact, |
167 | - XGMAC controller is not supported. | 191 | there are two MAC cores: one MAC is for MDIO Bus/PHY emulation |
168 | - Review the timer optimisation code to use an embedded device that seems to be | 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 | ||
169 | available in new chip generations. | 241 | available in new chip generations. |