stmmac: improve and up-to-date the documentation

(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

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

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 {

	int bus_id;

	int phy_addr;

	int interface;

	struct stmmac_mdio_bus_data *mdio_bus_data;

	int pbl;

	int clk_csr;

	int has_gmac;

	int tx_coe;

	int bugged_jumbo;

	int pmt;

	int force_sf_dma_mode;

	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 (*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.

 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.

- 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.

struct plat_stmmacphy_data {

 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.

The we have:

 struct stmmac_mdio_bus_data {

	int bus_id;

        int phy_addr;

        unsigned int phy_mask;

        int interface;

	int (*phy_reset)(void *priv);

        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.

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

 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.

Below an example how the structures above are using on ST platforms.

 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.

- 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

TODO:

- XGMAC controller is not supported.

- Review the timer optimisation code to use an embedded device that seems to be

 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.