Commit b50f7bca authored by Jesse Brandeburg's avatar Jesse Brandeburg Committed by David S. Miller
Browse files

intel-ethernet: clean up W=1 warnings in kdoc 



This takes care of all of the trivial W=1 fixes in the Intel
Ethernet drivers, which allows developers and maintainers to
build more of the networking tree with more complete warning
checks.

There are three classes of kdoc warnings fixed:
 - cannot understand function prototype: 'x'
 - Excess function parameter 'x' description in 'y'
 - Function parameter or member 'x' not described in 'y'

All of the changes were trivial comment updates on
function headers.

Inspired by Lee Jones' series of wireless work to do the same.
Compile tested only, and passes simple test of
$ git ls-files *.[ch] | egrep drivers/net/ethernet/intel | \
  xargs scripts/kernel-doc -none

Signed-off-by: default avatarJesse Brandeburg <jesse.brandeburg@intel.com>
Tested-by: default avatarAaron Brown <aaron.f.brown@intel.com>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent d0186842

drivers/net/ethernet/intel/e100.c

+1 −1
Original line number Diff line number Diff line
@@ -384,7 +384,7 @@ enum cb_status { 
	cb_ok       = 0x2000,

};



/**

/*

 * cb_command - Command Block flags

 * @cb_tx_nc:  0: controller does CRC (normal),  1: CRC from skb memory

 */

drivers/net/ethernet/intel/e1000/e1000_hw.c

+1 −6
Original line number Diff line number Diff line
@@ -1896,7 +1896,6 @@ void e1000_config_collision_dist(struct e1000_hw *hw) 
/**

 * e1000_config_mac_to_phy - sync phy and mac settings

 * @hw: Struct containing variables accessed by shared code

 * @mii_reg: data to write to the MII control register

 *

 * Sets MAC speed and duplex settings to reflect the those in the PHY

 * The contents of the PHY register containing the needed information need to
@@ -2921,7 +2920,7 @@ static s32 e1000_read_phy_reg_ex(struct e1000_hw *hw, u32 reg_addr, 
 *

 * @hw: Struct containing variables accessed by shared code

 * @reg_addr: address of the PHY register to write

 * @data: data to write to the PHY

 * @phy_data: data to write to the PHY

 *

 * Writes a value to a PHY register

 */
@@ -4777,8 +4776,6 @@ void e1000_reset_adaptive(struct e1000_hw *hw) 
/**

 * e1000_update_adaptive - update adaptive IFS

 * @hw: Struct containing variables accessed by shared code

 * @tx_packets: Number of transmits since last callback

 * @total_collisions: Number of collisions since last callback

 *

 * Called during the callback/watchdog routine to update IFS value based on

 * the ratio of transmits to collisions.
@@ -5063,8 +5060,6 @@ static s32 e1000_check_polarity(struct e1000_hw *hw, 
/**

 * e1000_check_downshift - Check if Downshift occurred

 * @hw: Struct containing variables accessed by shared code

 * @downshift: output parameter : 0 - No Downshift occurred.

 *                                1 - Downshift occurred.

 *

 * returns: - E1000_ERR_XXX

 *            E1000_SUCCESS

drivers/net/ethernet/intel/e1000/e1000_main.c

+25 −14
Original line number Diff line number Diff line
@@ -199,8 +199,10 @@ module_param(debug, int, 0); 
MODULE_PARM_DESC(debug, "Debug level (0=none,...,16=all)");



/**

 * e1000_get_hw_dev - return device

 * used by hardware layer to print debugging information

 * e1000_get_hw_dev - helper function for getting netdev

 * @hw: pointer to HW struct

 *

 * return device used by hardware layer to print debugging information

 *

 **/

struct net_device *e1000_get_hw_dev(struct e1000_hw *hw)
@@ -354,7 +356,7 @@ static void e1000_release_manageability(struct e1000_adapter *adapter) 


/**

 * e1000_configure - configure the hardware for RX and TX

 * @adapter = private board structure

 * @adapter: private board structure

 **/

static void e1000_configure(struct e1000_adapter *adapter)

{
@@ -3489,8 +3491,9 @@ static void e1000_dump(struct e1000_adapter *adapter) 
/**

 * e1000_tx_timeout - Respond to a Tx Hang

 * @netdev: network interface device structure

 * @txqueue: number of the Tx queue that hung (unused)

 **/

static void e1000_tx_timeout(struct net_device *netdev, unsigned int txqueue)

static void e1000_tx_timeout(struct net_device *netdev, unsigned int __always_unused txqueue)

{

	struct e1000_adapter *adapter = netdev_priv(netdev);
@@ -3787,7 +3790,8 @@ static irqreturn_t e1000_intr(int irq, void *data) 


/**

 * e1000_clean - NAPI Rx polling callback

 * @adapter: board private structure

 * @napi: napi struct containing references to driver info

 * @budget: budget given to driver for receive packets

 **/

static int e1000_clean(struct napi_struct *napi, int budget)

{
@@ -3818,6 +3822,7 @@ static int e1000_clean(struct napi_struct *napi, int budget) 
/**

 * e1000_clean_tx_irq - Reclaim resources after transmit completes

 * @adapter: board private structure

 * @tx_ring: ring to clean

 **/

static bool e1000_clean_tx_irq(struct e1000_adapter *adapter,

			       struct e1000_tx_ring *tx_ring)
@@ -3933,7 +3938,7 @@ static bool e1000_clean_tx_irq(struct e1000_adapter *adapter, 
 * @adapter:     board private structure

 * @status_err:  receive descriptor status and error fields

 * @csum:        receive descriptor csum field

 * @sk_buff:     socket buffer with received data

 * @skb:         socket buffer with received data

 **/

static void e1000_rx_checksum(struct e1000_adapter *adapter, u32 status_err,

			      u32 csum, struct sk_buff *skb)
@@ -3970,6 +3975,9 @@ static void e1000_rx_checksum(struct e1000_adapter *adapter, u32 status_err, 


/**

 * e1000_consume_page - helper function for jumbo Rx path

 * @bi: software descriptor shadow data

 * @skb: skb being modified

 * @length: length of data being added

 **/

static void e1000_consume_page(struct e1000_rx_buffer *bi, struct sk_buff *skb,

			       u16 length)
@@ -4003,6 +4011,7 @@ static void e1000_receive_skb(struct e1000_adapter *adapter, u8 status, 
/**

 * e1000_tbi_adjust_stats

 * @hw: Struct containing variables accessed by shared code

 * @stats: point to stats struct

 * @frame_len: The length of the frame in question

 * @mac_addr: The Ethernet destination address of the frame in question

 *
@@ -4548,6 +4557,8 @@ e1000_alloc_jumbo_rx_buffers(struct e1000_adapter *adapter, 
/**

 * e1000_alloc_rx_buffers - Replace used receive buffers; legacy & extended

 * @adapter: address of board private structure

 * @rx_ring: pointer to ring struct

 * @cleaned_count: number of new Rx buffers to try to allocate

 **/

static void e1000_alloc_rx_buffers(struct e1000_adapter *adapter,

				   struct e1000_rx_ring *rx_ring,
@@ -4662,7 +4673,7 @@ static void e1000_alloc_rx_buffers(struct e1000_adapter *adapter, 


/**

 * e1000_smartspeed - Workaround for SmartSpeed on 82541 and 82547 controllers.

 * @adapter:

 * @adapter: address of board private structure

 **/

static void e1000_smartspeed(struct e1000_adapter *adapter)

{
@@ -4718,10 +4729,10 @@ static void e1000_smartspeed(struct e1000_adapter *adapter) 
}



/**

 * e1000_ioctl -

 * @netdev:

 * @ifreq:

 * @cmd:

 * e1000_ioctl - handle ioctl calls

 * @netdev: pointer to our netdev

 * @ifr: pointer to interface request structure

 * @cmd: ioctl data

 **/

static int e1000_ioctl(struct net_device *netdev, struct ifreq *ifr, int cmd)

{
@@ -4737,9 +4748,9 @@ static int e1000_ioctl(struct net_device *netdev, struct ifreq *ifr, int cmd) 


/**

 * e1000_mii_ioctl -

 * @netdev:

 * @ifreq:

 * @cmd:

 * @netdev: pointer to our netdev

 * @ifr: pointer to interface request structure

 * @cmd: ioctl data

 **/

static int e1000_mii_ioctl(struct net_device *netdev, struct ifreq *ifr,

			   int cmd)

drivers/net/ethernet/intel/e1000e/80003es2lan.c

+0 −1
Original line number Diff line number Diff line
@@ -1072,7 +1072,6 @@ static s32 e1000_setup_copper_link_80003es2lan(struct e1000_hw *hw) 
/**

 *  e1000_cfg_on_link_up_80003es2lan - es2 link configuration after link-up

 *  @hw: pointer to the HW structure

 *  @duplex: current duplex setting

 *

 *  Configure the KMRN interface by applying last minute quirks for

 *  10/100 operation.

drivers/net/ethernet/intel/e1000e/ich8lan.c

+10 −6
Original line number Diff line number Diff line
@@ -743,7 +743,7 @@ static s32 e1000_init_mac_params_ich8lan(struct e1000_hw *hw) 
/**

 *  __e1000_access_emi_reg_locked - Read/write EMI register

 *  @hw: pointer to the HW structure

 *  @addr: EMI address to program

 *  @address: EMI address to program

 *  @data: pointer to value to read/write from/to the EMI address

 *  @read: boolean flag to indicate read or write

 *
@@ -2266,7 +2266,7 @@ static s32 e1000_k1_gig_workaround_hv(struct e1000_hw *hw, bool link) 
/**

 *  e1000_configure_k1_ich8lan - Configure K1 power state

 *  @hw: pointer to the HW structure

 *  @enable: K1 state to configure

 *  @k1_enable: K1 state to configure

 *

 *  Configure the K1 power state based on the provided parameter.

 *  Assumes semaphore already acquired.
@@ -2405,8 +2405,10 @@ static s32 e1000_set_mdio_slow_mode_hv(struct e1000_hw *hw) 
}



/**

 *  e1000_hv_phy_workarounds_ich8lan - A series of Phy workarounds to be

 *  done after every PHY reset.

 *  e1000_hv_phy_workarounds_ich8lan - apply PHY workarounds

 *  @hw: pointer to the HW structure

 *

 *  A series of PHY workarounds to be done after every PHY reset.

 **/

static s32 e1000_hv_phy_workarounds_ich8lan(struct e1000_hw *hw)

{
@@ -2694,8 +2696,10 @@ s32 e1000_lv_jumbo_workaround_ich8lan(struct e1000_hw *hw, bool enable) 
}



/**

 *  e1000_lv_phy_workarounds_ich8lan - A series of Phy workarounds to be

 *  done after every PHY reset.

 *  e1000_lv_phy_workarounds_ich8lan - apply ich8 specific workarounds

 *  @hw: pointer to the HW structure

 *

 *  A series of PHY workarounds to be done after every PHY reset.

 **/

static s32 e1000_lv_phy_workarounds_ich8lan(struct e1000_hw *hw)

{