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>

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>
Giuseppe CAVALLARO · David S. Miller
1 parent 36bcfe7d74
Showing 1 changed file with 136 additions and 64 deletions Side-by-side Diff
Documentation/networking/stmmac.txt
@@ -7,7 +7,7 @@
 (Synopsys IP blocks); it has been fully tested on STLinux platforms.
  
 Currently this network device driver is for all STM embedded MAC/GMAC
-(7xxx SoCs). Other platforms start using it i.e. ARM SPEAr.
+(i.e. 7xxx/5xxx SoCs) and it's known working on other platforms i.e. ARM SPEAr.
  
 DWC Ether MAC 10/100/1000 Universal version 3.41a and DWC Ether MAC 10/100
 Universal version 4.0 have been used for developing the first code
@@ -71,7 +71,7 @@
 the CPU while having the maximum throughput.
  
 4.4) WOL
-Wake up on Lan feature through Magic Frame is only supported for the GMAC
+Wake up on Lan feature through Magic and Unicast frames are supported for the GMAC
 core.
  
 4.5) DMA descriptors
  
  
@@ -91,11 +91,15 @@
 The driver is compatible with PAL to work with PHY and GPHY devices.
  
 4.9) Platform information
-Several information came from the platform; please refer to the
-driver's Header file in include/linux directory.
+Several driver's information can be passed through the platform
+These are included in the include/linux/stmmac.h header file
+and detailed below as well:
  
-struct plat_stmmacenet_data {
+ struct plat_stmmacenet_data {
 	int bus_id;
+	int phy_addr;
+	int interface;
+	struct stmmac_mdio_bus_data *mdio_bus_data;
 	int pbl;
 	int clk_csr;
 	int has_gmac;
  
  
  
  
  
  
@@ -103,68 +107,136 @@
 	int tx_coe;
 	int bugged_jumbo;
 	int pmt;
-        void (*fix_mac_speed)(void *priv, unsigned int speed);
-        void (*bus_setup)(unsigned long ioaddr);
-#ifdef CONFIG_STM_DRIVERS
-        struct stm_pad_config *pad_config;
-#endif
-        void *bsp_priv;
-};
+	int force_sf_dma_mode;
+	void (*fix_mac_speed)(void *priv, unsigned int speed);
+	void (*bus_setup)(void __iomem *ioaddr);
+	int (*init)(struct platform_device *pdev);
+	void (*exit)(struct platform_device *pdev);
+	void *bsp_priv;
+ };
  
 Where:
-- pbl (Programmable Burst Length) is maximum number of
-  beats to be transferred in one DMA transaction.
-  GMAC also enables the 4xPBL by default.
-- fix_mac_speed and bus_setup are used to configure internal target
-  registers (on STM platforms);
-- has_gmac: GMAC core is on board (get it at run-time in the next step);
-- bus_id: bus identifier.
-- tx_coe: core is able to perform the tx csum in HW.
-- enh_desc: if sets the MAC will use the enhanced descriptor structure.
-- clk_csr: CSR Clock range selection.
-- 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 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.
+ o pbl: the Programmable Burst Length is maximum number of beats to
+       be transferred in one DMA transaction.
+       GMAC also enables the 4xPBL by default.
+ o clk_csr: CSR Clock range selection.
+ 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.
+ 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.
+ 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.
+ o init/exit: callbacks used for calling a custom initialisation;
+	     this is sometime necessary on some platforms (e.g. ST boxes)
+	     where the HW needs to have set some PIO lines or system cfg
+	     registers.
+ o custom_cfg: this is a custom configuration that can be passed while
+	      initialising the resources.
  
-struct plat_stmmacphy_data {
-        int bus_id;
-        int phy_addr;
-        unsigned int phy_mask;
-        int interface;
-        int (*phy_reset)(void *priv);
-        void *priv;
-};
+The we have:
  
+ struct stmmac_mdio_bus_data {
+	int bus_id;
+	int (*phy_reset)(void *priv);
+	unsigned int phy_mask;
+	int *irqs;
+	int probed_phy_irq;
+ };
+
 Where:
-- bus_id: bus identifier;
-- phy_addr: physical address used for the attached phy device;
-            set it to -1 to get it at run-time;
-- interface: physical MII interface mode;
-- phy_reset: hook to reset HW function.
+ o bus_id: bus identifier;
+ 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.
  
-SOURCES:
-- Kconfig
-- Makefile
-- stmmac_main.c: main network device driver;
-- stmmac_mdio.c: mdio functions;
-- stmmac_ethtool.c: ethtool support;
-- stmmac_timer.[ch]: timer code used for mitigating the driver dma interrupts
-  Only tested on ST40 platforms based.
-- stmmac.h: private driver structure;
-- common.h: common definitions and VFTs;
-- descs.h: descriptor structure definitions;
-- dwmac1000_core.c: GMAC core functions;
-- dwmac1000_dma.c:  dma functions for the GMAC chip;
-- dwmac1000.h: specific header file for the GMAC;
-- dwmac100_core: MAC 100 core and dma code;
-- dwmac100_dma.c: dma funtions for the MAC chip;
-- dwmac1000.h: specific header file for the MAC;
-- dwmac_lib.c: generic DMA functions shared among chips
-- enh_desc.c: functions for handling enhanced descriptors
-- norm_desc.c: functions for handling normal descriptors
+Below an example how the structures above are using on ST platforms.
  
-TODO:
-- XGMAC controller is not supported.
-- Review the timer optimisation code to use an embedded device that seems to be
+ static struct plat_stmmacenet_data stxYYY_ethernet_platform_data = {
+	.pbl = 32,
+	.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 = {
+	.bus_id = 1,
+		|
+		|-> phy device on the bus_id 1
+	.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:
+  fixed_phy_add(PHY_POLL, 1, &stmmac0_fixed_phy_status));)
+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).
+
+4.10) List of source files:
+ o Kconfig
+ o Makefile
+ o stmmac_main.c: main network device driver;
+ o stmmac_mdio.c: mdio functions;
+ o stmmac_ethtool.c: ethtool support;
+ o stmmac_timer.[ch]: timer code used for mitigating the driver dma interrupts
+		      Only tested on ST40 platforms based.
+ o stmmac.h: private driver structure;
+ o common.h: common definitions and VFTs;
+ o descs.h: descriptor structure definitions;
+ o dwmac1000_core.c: GMAC core functions;
+ o dwmac1000_dma.c:  dma functions for the GMAC chip;
+ o dwmac1000.h: specific header file for the GMAC;
+ o dwmac100_core: MAC 100 core and dma code;
+ o dwmac100_dma.c: dma funtions for the MAC chip;
+ o dwmac1000.h: specific header file for the MAC;
+ o dwmac_lib.c: generic DMA functions shared among chips
+ o enh_desc.c: functions for handling enhanced descriptors
+ o norm_desc.c: functions for handling normal descriptors
+
+5) TODO:
+ o XGMAC is not supported.
+ o Review the timer optimisation code to use an embedded device that will be
   available in new chip generations.
...	...	@@ -7,7 +7,7 @@
7	7	(Synopsys IP blocks); it has been fully tested on STLinux platforms.
8	8
9	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	12	DWC Ether MAC 10/100/1000 Universal version 3.41a and DWC Ether MAC 10/100
13	13	Universal version 4.0 have been used for developing the first code
...	...	@@ -71,7 +71,7 @@
71	71	the CPU while having the maximum throughput.
72	72
73	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	75	core.
76	76
77	77	4.5) DMA descriptors
78	78
79	79
...	...	@@ -91,11 +91,15 @@
91	91	The driver is compatible with PAL to work with PHY and GPHY devices.
92	92
93	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.
	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:
96	97
97		-struct plat_stmmacenet_data {
	98	+ struct plat_stmmacenet_data {
98	99	int bus_id;
	100	+ int phy_addr;
	101	+ int interface;
	102	+ struct stmmac_mdio_bus_data *mdio_bus_data;
99	103	int pbl;
100	104	int clk_csr;
101	105	int has_gmac;
102	106
103	107
104	108
105	109
106	110
107	111
...	...	@@ -103,68 +107,136 @@
103	107	int tx_coe;
104	108	int bugged_jumbo;
105	109	int pmt;
106		- void (fix_mac_speed)(void priv, unsigned int speed);
107		- void (*bus_setup)(unsigned long ioaddr);
108		-#ifdef CONFIG_STM_DRIVERS
109		- struct stm_pad_config *pad_config;
110		-#endif
111		- void *bsp_priv;
112		-};
	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	+ };
113	117
114	118	Where:
115		-- pbl (Programmable Burst Length) is maximum number of
116		- beats to be transferred in one DMA transaction.
117		- GMAC also enables the 4xPBL by default.
118		-- fix_mac_speed and bus_setup are used to configure internal target
119		- registers (on STM platforms);
120		-- has_gmac: GMAC core is on board (get it at run-time in the next step);
121		-- bus_id: bus identifier.
122		-- tx_coe: core is able to perform the tx csum in HW.
123		-- enh_desc: if sets the MAC will use the enhanced descriptor structure.
124		-- clk_csr: CSR Clock range selection.
125		-- bugged_jumbo: some HWs are not able to perform the csum in HW for
126		- over-sized frames due to limited buffer sizes. Setting this
127		- flag the csum will be done in SW on JUMBO frames.
	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.
128	151
129		-struct plat_stmmacphy_data {
130		- int bus_id;
131		- int phy_addr;
132		- unsigned int phy_mask;
133		- int interface;
134		- int (phy_reset)(void priv);
135		- void *priv;
136		-};
	152	+The we have:
137	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	+ };
	161	+
138	162	Where:
139		-- bus_id: bus identifier;
140		-- phy_addr: physical address used for the attached phy device;
141		- set it to -1 to get it at run-time;
142		-- interface: physical MII interface mode;
143		-- phy_reset: hook to reset HW function.
	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.
144	168
145		-SOURCES:
146		-- Kconfig
147		-- Makefile
148		-- stmmac_main.c: main network device driver;
149		-- stmmac_mdio.c: mdio functions;
150		-- stmmac_ethtool.c: ethtool support;
151		-- stmmac_timer.[ch]: timer code used for mitigating the driver dma interrupts
152		- Only tested on ST40 platforms based.
153		-- stmmac.h: private driver structure;
154		-- common.h: common definitions and VFTs;
155		-- descs.h: descriptor structure definitions;
156		-- dwmac1000_core.c: GMAC core functions;
157		-- dwmac1000_dma.c: dma functions for the GMAC chip;
158		-- dwmac1000.h: specific header file for the GMAC;
159		-- dwmac100_core: MAC 100 core and dma code;
160		-- dwmac100_dma.c: dma funtions for the MAC chip;
161		-- dwmac1000.h: specific header file for the MAC;
162		-- dwmac_lib.c: generic DMA functions shared among chips
163		-- enh_desc.c: functions for handling enhanced descriptors
164		-- norm_desc.c: functions for handling normal descriptors
	169	+Below an example how the structures above are using on ST platforms.
165	170
166		-TODO:
167		-- XGMAC controller is not supported.
168		-- Review the timer optimisation code to use an embedded device that seems to be
	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
169	241	available in new chip generations.