282 lines
10 KiB
Plaintext
282 lines
10 KiB
Plaintext
STMicroelectronics 10/100/1000 Synopsys Ethernet driver
|
|
|
|
Copyright (C) 2007-2010 STMicroelectronics Ltd
|
|
Author: Giuseppe Cavallaro <peppe.cavallaro@st.com>
|
|
|
|
This is the driver for the MAC 10/100/1000 on-chip Ethernet controllers
|
|
(Synopsys IP blocks); it has been fully tested on STLinux platforms.
|
|
|
|
Currently this network device driver is for all STM embedded MAC/GMAC
|
|
(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
|
|
implementation.
|
|
|
|
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)
|
|
|
|
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;
|
|
tx_coe: Enable/Disable Tx Checksum Offload engine;
|
|
watchdog: transmit timeout (in milliseconds);
|
|
flow_ctrl: Flow control ability [on/off];
|
|
pause: Flow Control Pause Time;
|
|
tmrate: timer period (only if timer optimisation is configured).
|
|
|
|
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.
|
|
Once the controller has finished transmitting the packet, an interrupt is
|
|
triggered; So the driver will be able to release the socket buffers.
|
|
By default, the driver sets the NETIF_F_SG bit in the features field of the
|
|
net_device structure enabling the scatter/gather feature.
|
|
|
|
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.
|
|
This is based on NAPI so the interrupt handler signals only if there is work to be
|
|
done, and it exits.
|
|
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
|
|
buffers in order to avoid the memcpy (Zero-copy).
|
|
|
|
4.3) Timer-Driver Interrupt
|
|
Instead of having the device that asynchronously notifies the frame receptions, the
|
|
driver configures a timer to generate an interrupt at regular intervals.
|
|
Based on the granularity of the timer, the frames that are received by the device
|
|
will experience different levels of latency. Some NICs have dedicated timer
|
|
device to perform this task. STMMAC can use either the RTC device or the TMU
|
|
channel 2 on STLinux platforms.
|
|
The timers frequency can be passed to the driver as parameter; when change it,
|
|
take care of both hardware capability and network stability/performance impact.
|
|
Several performance tests on STM platforms showed this optimisation allows to spare
|
|
the CPU while having the maximum throughput.
|
|
|
|
4.4) WOL
|
|
Wake up on Lan feature through Magic and Unicast frames are supported for the GMAC
|
|
core.
|
|
|
|
4.5) DMA descriptors
|
|
Driver handles both normal and enhanced descriptors. The latter has been only
|
|
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.
|
|
|
|
4.6) Ethtool support
|
|
Ethtool is supported. Driver statistics and internal errors can be taken using:
|
|
ethtool -S ethX command. It is possible to dump registers etc.
|
|
|
|
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
|
|
The driver is compatible with PAL to work with PHY and GPHY devices.
|
|
|
|
4.9) Platform information
|
|
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 enh_desc;
|
|
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)(void __iomem *ioaddr);
|
|
int (*init)(struct platform_device *pdev);
|
|
void (*exit)(struct platform_device *pdev);
|
|
void *bsp_priv;
|
|
};
|
|
|
|
Where:
|
|
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.
|
|
|
|
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:
|
|
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.
|
|
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) 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
|
|
|
|
Compiling the Kernel with CONFIG_DEBUG_FS and enabling the
|
|
STMMAC_DEBUG_FS option the driver will export the following
|
|
debugfs entries:
|
|
|
|
/sys/kernel/debug/stmmaceth/descriptors_status
|
|
To show the DMA TX/RX descriptor rings
|
|
|
|
Developer can also use the "debug" module parameter to get
|
|
further debug information.
|
|
|
|
In the end, there are other macros (that cannot be enabled
|
|
via menuconfig) to turn-on the RX/TX DMA debugging,
|
|
specific MAC core debug printk etc. Others to enable the
|
|
debug in the TX and RX processes.
|
|
All these are only useful during the developing stage
|
|
and should never enabled inside the code for general usage.
|
|
In fact, these can generate an huge amount of debug messages.
|
|
|
|
6) 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.
|