leandrof/linux
1
0
Fork 0
forked from Minki/linux
Code Issues Pull Requests Packages Projects Releases Wiki Activity

stmmac: improve/review and fix kernel-doc

Browse Source 
this patch reviews/improves and adds some fixes in the code doc.
Also kernel-doc passes w/o any warnings.

Signed-off-by: Giuseppe Cavallaro <peppe.cavallaro@st.com>
Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
Giuseppe CAVALLARO 2013-04-08 02:10:00 +00:00 committed by David S. Miller
parent 49cfbf675c
commit 32ceabcad3
2 changed files with 142 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
drivers/net/ethernet/stmicro/stmmac/stmmac_main.c
View File

@ -81,14 +81,14 @@
#define JUMBO_LEN 9000
/* Module parameters */
#define TX_TIMEO 5000 /* default 5 seconds */
#define TX_TIMEO 5000
static int watchdog = TX_TIMEO;
module_param(watchdog, int, S_IRUGO | S_IWUSR);
MODULE_PARM_DESC(watchdog, "Transmit timeout in milliseconds");
MODULE_PARM_DESC(watchdog, "Transmit timeout in milliseconds (default 5s)");
static int debug = -1; /* -1: default, 0: no output, 16: all */
static int debug = -1;
module_param(debug, int, S_IRUGO | S_IWUSR);
MODULE_PARM_DESC(debug, "Message Level (0: no output, 16: all)");
MODULE_PARM_DESC(debug, "Message Level (-1: default, 0: no output, 16: all)");
int phyaddr = -1;
module_param(phyaddr, int, S_IRUGO);
@ -173,6 +173,18 @@ static void stmmac_verify_args(void)
eee_timer = STMMAC_DEFAULT_LPI_TIMER;
}
/**
* stmmac_clk_csr_set - dynamically set the MDC clock
* @priv: driver private structure
* Description: this is to dynamically set the MDC clock according to the csr
* clock input.
* Note:
* If a specific clk_csr value is passed from the platform
* this means that the CSR Clock Range selection cannot be
* changed at run-time and it is fixed (as reported in the driver
* documentation). Viceversa the driver will try to set the MDC
* clock dynamically according to the actual clock input.
*/
static void stmmac_clk_csr_set(struct stmmac_priv *priv)
{
u32 clk_rate;
@ -222,8 +234,11 @@ static inline u32 stmmac_tx_avail(struct stmmac_priv *priv)
return priv->dirty_tx + priv->dma_tx_size - priv->cur_tx - 1;
}
/* On some ST platforms, some HW system configuraton registers have to be
* set according to the link speed negotiated.
/**
* stmmac_hw_fix_mac_speed: callback for speed selection
* @priv: driver private structure
* Description: on some platforms (e.g. ST), some HW system configuraton
* registers have to be set according to the link speed negotiated.
*/
static inline void stmmac_hw_fix_mac_speed(struct stmmac_priv *priv)
{
@ -234,6 +249,11 @@ static inline void stmmac_hw_fix_mac_speed(struct stmmac_priv *priv)
phydev->speed);
}
/**
* stmmac_enable_eee_mode: Check and enter in LPI mode
* @priv: driver private structure
* Description: this function is to verify and enter in LPI mode for EEE.
*/
static void stmmac_enable_eee_mode(struct stmmac_priv *priv)
{
/* Check and enter in LPI mode */
@ -242,19 +262,24 @@ static void stmmac_enable_eee_mode(struct stmmac_priv *priv)
priv->hw->mac->set_eee_mode(priv->ioaddr);
}
/**
* stmmac_disable_eee_mode: disable/exit from EEE
* @priv: driver private structure
* Description: this function is to exit and disable EEE in case of
* LPI state is true. This is called by the xmit.
*/
void stmmac_disable_eee_mode(struct stmmac_priv *priv)
{
/* Exit and disable EEE in case of we are are in LPI state. */
priv->hw->mac->reset_eee_mode(priv->ioaddr);
del_timer_sync(&priv->eee_ctrl_timer);
priv->tx_path_in_lpi_mode = false;
}
/**
* stmmac_eee_ctrl_timer
* stmmac_eee_ctrl_timer: EEE TX SW timer.
* @arg : data hook
* Description:
* If there is no data transfer and if we are not in LPI state,
* if there is no data transfer and if we are not in LPI state,
* then MAC Transmitter can be moved to LPI state.
*/
static void stmmac_eee_ctrl_timer(unsigned long arg)
@ -266,8 +291,8 @@ static void stmmac_eee_ctrl_timer(unsigned long arg)
}
/**
* stmmac_eee_init
* @priv: private device pointer
* stmmac_eee_init: init EEE
* @priv: driver private structure
* Description:
* If the EEE support has been enabled while configuring the driver,
* if the GMAC actually supports the EEE (from the HW cap reg) and the
@ -303,18 +328,22 @@ out:
return ret;
}
/**
* stmmac_eee_adjust: adjust HW EEE according to the speed
* @priv: driver private structure
* Description:
* When the EEE has been already initialised we have to
* modify the PLS bit in the LPI ctrl & status reg according
* to the PHY link status. For this reason.
*/
static void stmmac_eee_adjust(struct stmmac_priv *priv)
{
/* When the EEE has been already initialised we have to
* modify the PLS bit in the LPI ctrl & status reg according
* to the PHY link status. For this reason.
*/
if (priv->eee_enabled)
priv->hw->mac->set_eee_pls(priv->ioaddr, priv->phydev->link);
}
/* stmmac_get_tx_hwtstamp:
* @priv : pointer to private device structure.
/* stmmac_get_tx_hwtstamp: get HW TX timestamps
* @priv: driver private structure
* @entry : descriptor index to be used.
* @skb : the socket buffer
* Description :
@ -356,8 +385,8 @@ static void stmmac_get_tx_hwtstamp(struct stmmac_priv *priv,
return;
}
/* stmmac_get_rx_hwtstamp:
* @priv : pointer to private device structure.
/* stmmac_get_rx_hwtstamp: get HW RX timestamps
* @priv: driver private structure
* @entry : descriptor index to be used.
* @skb : the socket buffer
* Description :
@ -618,6 +647,13 @@ static int stmmac_hwtstamp_ioctl(struct net_device *dev, struct ifreq *ifr)
sizeof(struct hwtstamp_config)) ? -EFAULT : 0;
}
/**
* stmmac_init_ptp: init PTP
* @priv: driver private structure
* Description: this is to verify if the HW supports the PTPv1 or v2.
* This is done by looking at the HW cap. register.
* Also it registers the ptp driver.
*/
static int stmmac_init_ptp(struct stmmac_priv *priv)
{
if (!(priv->dma_cap.time_stamp || priv->dma_cap.atime_stamp))
@ -740,6 +776,13 @@ static void stmmac_adjust_link(struct net_device *dev)
DBG(probe, DEBUG, "stmmac_adjust_link: exiting\n");
}
/**
* stmmac_check_pcs_mode: verify if RGMII/SGMII is supported
* @priv: driver private structure
* Description: this is to verify if the HW supports the PCS.
* Physical Coding Sublayer (PCS) interface that can be used when the MAC is
* configured for the TBI, RTBI, or SGMII PHY interface.
*/
static void stmmac_check_pcs_mode(struct stmmac_priv *priv)
{
int interface = priv->plat->interface;
@ -821,9 +864,10 @@ static int stmmac_init_phy(struct net_device *dev)
}
/**
* stmmac_display_ring
* @p: pointer to the ring.
* stmmac_display_ring: display ring
* @head: pointer to the head of the ring passed.
* @size: size of the ring.
* @extend_desc: to verify if extended descriptors are used.
* Description: display the control/status and buffer descriptors.
*/
static void stmmac_display_ring(void *head, int size, int extend_desc)
@ -887,6 +931,12 @@ static int stmmac_set_bfsize(int mtu, int bufsize)
return ret;
}
/**
* stmmac_clear_descriptors: clear descriptors
* @priv: driver private structure
* Description: this function is called to clear the tx and rx descriptors
* in case of both basic and extended descriptors are used.
*/
static void stmmac_clear_descriptors(struct stmmac_priv *priv)
{
int i;
@ -1129,7 +1179,7 @@ static void free_dma_desc_resources(struct stmmac_priv *priv)
/**
* stmmac_dma_operation_mode - HW DMA operation mode
* @priv : pointer to the private device structure.
* @priv: driver private structure
* Description: it sets the DMA operation mode: tx/rx DMA thresholds
* or Store-And-Forward capability.
*/
@ -1153,7 +1203,7 @@ static void stmmac_dma_operation_mode(struct stmmac_priv *priv)
/**
* stmmac_tx_clean:
* @priv: private data pointer
* @priv: driver private structure
* Description: it reclaims resources after transmission completes.
*/
static void stmmac_tx_clean(struct stmmac_priv *priv)
@ -1245,8 +1295,8 @@ static inline void stmmac_disable_dma_irq(struct stmmac_priv *priv)
/**
* stmmac_tx_err:
* @priv: pointer to the private device structure
* stmmac_tx_err: irq tx error mng function
* @priv: driver private structure
* Description: it cleans the descriptors and restarts the transmission
* in case of errors.
*/
@ -1275,6 +1325,14 @@ static void stmmac_tx_err(struct stmmac_priv *priv)
netif_wake_queue(priv->dev);
}
/**
* stmmac_dma_interrupt: DMA ISR
* @priv: driver private structure
* Description: this is the DMA ISR. It is called by the main ISR.
* It calls the dwmac dma routine to understand which type of interrupt
* happened. In case of there is a Normal interrupt and either TX or RX
* interrupt happened so the NAPI is scheduled.
*/
static void stmmac_dma_interrupt(struct stmmac_priv *priv)
{
int status;
@ -1297,13 +1355,16 @@ static void stmmac_dma_interrupt(struct stmmac_priv *priv)
stmmac_tx_err(priv);
}
/**
* stmmac_mmc_setup: setup the Mac Management Counters (MMC)
* @priv: driver private structure
* Description: this masks the MMC irq, in fact, the counters are managed in SW.
*/
static void stmmac_mmc_setup(struct stmmac_priv *priv)
{
unsigned int mode = MMC_CNTRL_RESET_ON_READ | MMC_CNTRL_COUNTER_RESET |
MMC_CNTRL_PRESET | MMC_CNTRL_FULL_HALF_PRESET;
/* Mask MMC irq, counters are managed in SW and registers
* are cleared on each READ eventually. */
dwmac_mmc_intr_all_mask(priv->ioaddr);
if (priv->dma_cap.rmon) {
@ -1332,9 +1393,11 @@ static u32 stmmac_get_synopsys_id(struct stmmac_priv *priv)
}
/**
* stmmac_selec_desc_mode
* @priv : private structure
* Description: select the Enhanced/Alternate or Normal descriptors
* stmmac_selec_desc_mode: to select among: normal/alternate/extend descriptors
* @priv: driver private structure
* Description: select the Enhanced/Alternate or Normal descriptors.
* In case of Enhanced/Alternate, it looks at the extended descriptors are
* supported by the HW cap. register.
*/
static void stmmac_selec_desc_mode(struct stmmac_priv *priv)
{
@ -1356,8 +1419,8 @@ static void stmmac_selec_desc_mode(struct stmmac_priv *priv)
}
/**
* stmmac_get_hw_features
* @priv : private device pointer
* stmmac_get_hw_features: get MAC capabilities from the HW cap. register.
* @priv: driver private structure
* Description:
* new GMAC chip generations have a new register to indicate the
* presence of the optional feature/functions.
@ -1415,10 +1478,15 @@ static int stmmac_get_hw_features(struct stmmac_priv *priv)
return hw_cap;
}
/**
* stmmac_check_ether_addr: check if the MAC addr is valid
* @priv: driver private structure
* Description:
* it is to verify if the MAC address is valid, in case of failures it
* generates a random MAC address
*/
static void stmmac_check_ether_addr(struct stmmac_priv *priv)
{
/* verify if the MAC address is valid, in case of failures it
* generates a random MAC address */
if (!is_valid_ether_addr(priv->dev->dev_addr)) {
priv->hw->mac->get_umac_addr((void __iomem *)
priv->dev->base_addr,
@ -1430,15 +1498,20 @@ static void stmmac_check_ether_addr(struct stmmac_priv *priv)
priv->dev->dev_addr);
}
/**
* stmmac_init_dma_engine: DMA init.
* @priv: driver private structure
* Description:
* It inits the DMA invoking the specific MAC/GMAC callback.
* Some DMA parameters can be passed from the platform;
* in case of these are not passed a default is kept for the MAC or GMAC.
*/
static int stmmac_init_dma_engine(struct stmmac_priv *priv)
{
int pbl = DEFAULT_DMA_PBL, fixed_burst = 0, burst_len = 0;
int mixed_burst = 0;
int atds = 0;
/* Some DMA parameters can be passed from the platform;
* in case of these are not passed we keep a default
* (good for all the chips) and init the DMA! */
if (priv->plat->dma_cfg) {
pbl = priv->plat->dma_cfg->pbl;
fixed_burst = priv->plat->dma_cfg->fixed_burst;
@ -1455,7 +1528,7 @@ static int stmmac_init_dma_engine(struct stmmac_priv *priv)
}
/**
* stmmac_tx_timer:
* stmmac_tx_timer: mitigation sw timer for tx.
* @data: data pointer
* Description:
* This is the timer handler to directly invoke the stmmac_tx_clean.
@ -1468,8 +1541,8 @@ static void stmmac_tx_timer(unsigned long data)
}
/**
* stmmac_tx_timer:
* @priv: private data structure
* stmmac_init_tx_coalesce: init tx mitigation options.
* @priv: driver private structure
* Description:
* This inits the transmit coalesce parameters: i.e. timer rate,
* timer handler and default threshold used for enabling the
@ -1699,10 +1772,12 @@ static int stmmac_release(struct net_device *dev)
}
/**
* stmmac_xmit:
* stmmac_xmit: Tx entry point of the driver
* @skb : the socket buffer
* @dev : device pointer
* Description : Tx entry point of the driver.
* Description : this is the tx entry point of the driver.
* It programs the chain or the ring and supports oversized frames
* and SG feature.
*/
static netdev_tx_t stmmac_xmit(struct sk_buff *skb, struct net_device *dev)
{
@ -1868,6 +1943,12 @@ static netdev_tx_t stmmac_xmit(struct sk_buff *skb, struct net_device *dev)
return NETDEV_TX_OK;
}
/**
* stmmac_rx_refill: refill used skb preallocated buffers
* @priv: driver private structure
* Description : this is to reallocate the skb for the reception process
* that is based on zero-copy.
*/
static inline void stmmac_rx_refill(struct stmmac_priv *priv)
{
unsigned int rxsize = priv->dma_rx_size;
@ -1907,6 +1988,13 @@ static inline void stmmac_rx_refill(struct stmmac_priv *priv)
}
}
/**
* stmmac_rx_refill: refill used skb preallocated buffers
* @priv: driver private structure
* @limit: napi bugget.
* Description : this the function called by the napi poll method.
* It gets all the frames inside the ring.
*/
static int stmmac_rx(struct stmmac_priv *priv, int limit)
{
unsigned int rxsize = priv->dma_rx_size;
@ -2170,6 +2258,14 @@ static netdev_features_t stmmac_fix_features(struct net_device *dev,
return features;
}
/**
* stmmac_interrupt - main ISR
* @irq: interrupt number.
* @dev_id: to pass the net device pointer.
* Description: this is the main driver interrupt service routine.
* It calls the DMA ISR and also the core ISR to manage PMT, MMC, LPI
* interrupts.
*/
static irqreturn_t stmmac_interrupt(int irq, void *dev_id)
{
struct net_device *dev = (struct net_device *)dev_id;
@ -2218,7 +2314,7 @@ static void stmmac_poll_controller(struct net_device *dev)
* a proprietary structure used to pass information to the driver.
* @cmd: IOCTL command
* Description:
* Currently it supports just the phy_mii_ioctl(...) and HW time stamping.
* Currently it supports the phy_mii_ioctl(...) and HW time stamping.
*/
static int stmmac_ioctl(struct net_device *dev, struct ifreq *rq, int cmd)
{
@ -2451,7 +2547,7 @@ static const struct net_device_ops stmmac_netdev_ops = {
/**
* stmmac_hw_init - Init the MAC device
* @priv : pointer to the private device structure.
* @priv: driver private structure
* Description: this function detects which MAC device
* (GMAC/MAC10-100) has to attached, checks the HW capability
* (if supported) and sets the driver's features (for example

8
drivers/net/ethernet/stmicro/stmmac/stmmac_ptp.c
View File

@ -174,9 +174,7 @@ static struct ptp_clock_info stmmac_ptp_clock_ops = {
/**
* stmmac_ptp_register
*
* @ndev: net device pointer
*
* @priv: driver private structure
* Description: this function will register the ptp clock driver
* to kernel. It also does some house keeping work.
*/
@ -199,9 +197,7 @@ int stmmac_ptp_register(struct stmmac_priv *priv)
/**
* stmmac_ptp_unregister
*
* @ndev: net device pointer
*
* @priv: driver private structure
* Description: this function will remove/unregister the ptp clock driver
* from the kernel.
*/