[PATCH v4 00/27]Fix several bad kernel-doc markups

[PATCH v4 00/27]Fix several bad kernel-doc markups

[Mauro Carvalho Chehab]

Kernel-doc has always be limited to a probably bad documented
rule:

The kernel-doc markups should appear *imediatelly before* the
function or data structure that it documents.

On other words, if a C file would contain something like this:

	/**
	 * foo - function foo
	 * @args: foo args
	 */
	static inline void bar(int args);

	/**
	 * bar - function bar
	 * @args: foo args
	 */
	static inline void foo(void *args);


The output (in ReST format) will be:

	.. c:function:: void bar (int args)

	   function foo

	**Parameters**

	``int args``
	  foo args


	.. c:function:: void foo (void *args)

	   function bar

	**Parameters**

	``void *args``
	  foo args

Which is clearly a wrong result.  Before this changeset, 
not even a warning is produced on such cases.

As placing such markups just before the documented
data is a common practice, on most cases this is fine.

However, as patches touch things, identifiers may be
renamed, and people may forget to update the kernel-doc
markups to follow such changes.

This has been happening for quite a while, as there are
lots of files with kernel-doc problems.

This series address those issues and add a file at the
end that will enforce that the identifier will match the
kernel-doc markup, avoiding this problem from
keep happening as time goes by.

This series is based on current upstream tree.

@maintainers: feel free to pick the patches and
apply them directly on your trees, as all patches on 
this series are independent from the other ones.

--

v4:

  - Patches got rebased and got some acks.

Mauro Carvalho Chehab (27):
  net: phy: fix kernel-doc markups
  net: datagram: fix some kernel-doc markups
  net: core: fix some kernel-doc markups
  s390: fix kernel-doc markups
  drm: fix some kernel-doc markups
  HSI: fix a kernel-doc markup
  IB: fix kernel-doc markups
  parport: fix a kernel-doc markup
  rapidio: fix kernel-doc a markup
  video: fix some kernel-doc markups
  fs: fix kernel-doc markups
  jbd2: fix kernel-doc markups
  pstore/zone: fix a kernel-doc markup
  completion: fix kernel-doc markups
  firmware: stratix10-svc: fix kernel-doc markups
  connector: fix a kernel-doc markup
  lib/crc7: fix a kernel-doc markup
  hrtimer: fix kernel-doc markups
  genirq: fix kernel-doc markups
  list: fix a typo at the kernel-doc markup
  memblock: fix kernel-doc markups
  w1: fix a kernel-doc markup
  resource: fix kernel-doc markups
  shed: fix kernel-doc markup
  mm: fix kernel-doc markups
  selftests: kselftest_harness.h: partially fix kernel-doc markups
  scripts: kernel-doc: validate kernel-doc markup with the actual names

 arch/s390/include/asm/ccwdev.h                |  2 +-
 arch/s390/include/asm/cio.h                   |  2 +-
 drivers/gpu/drm/drm_atomic_state_helper.c     |  2 +-
 drivers/gpu/drm/drm_connector.c               |  3 +-
 drivers/gpu/drm/drm_dp_helper.c               |  2 +-
 drivers/gpu/drm/drm_framebuffer.c             |  2 +-
 drivers/gpu/drm/drm_gem.c                     |  4 +-
 drivers/gpu/drm/drm_gem_vram_helper.c         |  2 +-
 drivers/gpu/drm/drm_mode_object.c             |  2 +-
 drivers/gpu/drm/drm_modes.c                   |  4 +-
 drivers/gpu/drm/drm_scdc_helper.c             |  2 +-
 drivers/gpu/drm/i915/display/intel_dpll_mgr.c |  2 +-
 drivers/gpu/drm/i915/i915_gem_evict.c         |  2 +-
 drivers/gpu/drm/i915/i915_perf.c              |  8 ++-
 drivers/gpu/drm/scheduler/sched_main.c        |  2 +-
 drivers/gpu/drm/v3d/v3d_sched.c               |  2 +-
 drivers/gpu/drm/vc4/vc4_bo.c                  |  2 +-
 drivers/hsi/hsi_core.c                        |  2 +-
 drivers/infiniband/core/cm.c                  |  5 +-
 drivers/infiniband/core/cq.c                  |  4 +-
 drivers/infiniband/core/iwpm_util.h           |  2 +-
 drivers/infiniband/core/sa_query.c            |  3 +-
 drivers/infiniband/core/verbs.c               |  4 +-
 drivers/infiniband/sw/rdmavt/ah.c             |  2 +-
 drivers/infiniband/sw/rdmavt/mcast.c          | 12 ++--
 drivers/infiniband/sw/rdmavt/qp.c             |  8 +--
 drivers/infiniband/ulp/iser/iscsi_iser.c      |  2 +-
 .../infiniband/ulp/opa_vnic/opa_vnic_encap.h  |  2 +-
 .../ulp/opa_vnic/opa_vnic_vema_iface.c        |  2 +-
 drivers/infiniband/ulp/srpt/ib_srpt.h         |  2 +-
 drivers/net/phy/mdio_bus.c                    |  2 +-
 drivers/net/phy/phy-c45.c                     |  2 +-
 drivers/net/phy/phy.c                         |  2 +-
 drivers/net/phy/phy_device.c                  |  2 +-
 drivers/net/phy/phylink.c                     |  2 +-
 drivers/parport/share.c                       |  2 +-
 drivers/rapidio/rio.c                         |  2 +-
 drivers/video/fbdev/core/fbcmap.c             |  2 +-
 drivers/video/hdmi.c                          |  3 +-
 fs/dcache.c                                   | 72 +++++++++----------
 fs/inode.c                                    |  4 +-
 fs/jbd2/journal.c                             | 34 ++++-----
 fs/jbd2/transaction.c                         | 31 ++++----
 fs/pstore/zone.c                              |  2 +-
 fs/seq_file.c                                 |  5 +-
 fs/super.c                                    | 12 ++--
 include/drm/drm_atomic_helper.h               |  4 +-
 include/drm/drm_connector.h                   |  2 +-
 include/drm/drm_device.h                      |  2 +-
 include/drm/drm_dsc.h                         |  3 +-
 include/drm/drm_gem_vram_helper.h             |  8 +--
 include/linux/completion.h                    | 10 ++-
 include/linux/connector.h                     |  2 +-
 .../firmware/intel/stratix10-svc-client.h     | 10 +--
 include/linux/hrtimer.h                       |  6 +-
 include/linux/jbd2.h                          |  2 +-
 include/linux/list.h                          |  2 +-
 include/linux/memblock.h                      |  4 +-
 include/linux/netdevice.h                     | 11 ++-
 include/linux/parport.h                       | 31 ++++++++
 include/linux/w1.h                            |  2 +-
 include/rdma/ib_verbs.h                       | 11 +++
 kernel/irq/chip.c                             |  2 +-
 kernel/irq/generic-chip.c                     |  2 +-
 kernel/resource.c                             | 24 ++++---
 kernel/sched/core.c                           | 16 ++---
 kernel/sched/fair.c                           |  2 +-
 kernel/time/hrtimer.c                         |  2 +-
 lib/crc7.c                                    |  2 +-
 mm/gup.c                                      | 24 ++++---
 mm/page_alloc.c                               | 16 ++---
 mm/truncate.c                                 | 10 ++-
 net/core/datagram.c                           |  2 +-
 net/core/dev.c                                |  4 +-
 net/core/skbuff.c                             |  2 +-
 net/ethernet/eth.c                            |  6 +-
 net/sunrpc/rpc_pipe.c                         |  3 +-
 scripts/kernel-doc                            | 62 +++++++++++-----
 tools/testing/selftests/kselftest_harness.h   | 22 +++---
 79 files changed, 350 insertions(+), 235 deletions(-)

-- 
2.28.0

[PATCH v4 01/27] net: phy: fix kernel-doc markups

[Mauro Carvalho Chehab]

Some functions have different names between their prototypes
and the kernel-doc markup.

Reviewed-by: Andrew Lunn <andrew@lunn.ch>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/net/phy/mdio_bus.c   | 2 +-
 drivers/net/phy/phy-c45.c    | 2 +-
 drivers/net/phy/phy.c        | 2 +-
 drivers/net/phy/phy_device.c | 2 +-
 drivers/net/phy/phylink.c    | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/drivers/net/phy/mdio_bus.c b/drivers/net/phy/mdio_bus.c
index 757e950fb745..e59067c64e97 100644
--- a/drivers/net/phy/mdio_bus.c
+++ b/drivers/net/phy/mdio_bus.c
@@ -455,41 +455,41 @@ static void of_mdiobus_link_mdiodev(struct mii_bus *bus,
 
 		addr = of_mdio_parse_addr(dev, child);
 		if (addr < 0)
 			continue;
 
 		if (addr == mdiodev->addr) {
 			dev->of_node = child;
 			dev->fwnode = of_fwnode_handle(child);
 			return;
 		}
 	}
 }
 #else /* !IS_ENABLED(CONFIG_OF_MDIO) */
 static inline void of_mdiobus_link_mdiodev(struct mii_bus *mdio,
 					   struct mdio_device *mdiodev)
 {
 }
 #endif
 
 /**
- * mdiobus_create_device_from_board_info - create a full MDIO device given
+ * mdiobus_create_device - create a full MDIO device given
  * a mdio_board_info structure
  * @bus: MDIO bus to create the devices on
  * @bi: mdio_board_info structure describing the devices
  *
  * Returns 0 on success or < 0 on error.
  */
 static int mdiobus_create_device(struct mii_bus *bus,
 				 struct mdio_board_info *bi)
 {
 	struct mdio_device *mdiodev;
 	int ret = 0;
 
 	mdiodev = mdio_device_create(bus, bi->mdio_addr);
 	if (IS_ERR(mdiodev))
 		return -ENODEV;
 
 	strncpy(mdiodev->modalias, bi->modalias,
 		sizeof(mdiodev->modalias));
 	mdiodev->bus_match = mdio_device_bus_match;
 	mdiodev->dev.platform_data = (void *)bi->platform_data;
diff --git a/drivers/net/phy/phy-c45.c b/drivers/net/phy/phy-c45.c
index bd11e62bfdfe..077f2929c45e 100644
--- a/drivers/net/phy/phy-c45.c
+++ b/drivers/net/phy/phy-c45.c
@@ -1,32 +1,32 @@
 // SPDX-License-Identifier: GPL-2.0-only
 /*
  * Clause 45 PHY support
  */
 #include <linux/ethtool.h>
 #include <linux/export.h>
 #include <linux/mdio.h>
 #include <linux/mii.h>
 #include <linux/phy.h>
 
 /**
- * genphy_c45_setup_forced - configures a forced speed
+ * genphy_c45_pma_setup_forced - configures a forced speed
  * @phydev: target phy_device struct
  */
 int genphy_c45_pma_setup_forced(struct phy_device *phydev)
 {
 	int ctrl1, ctrl2, ret;
 
 	/* Half duplex is not supported */
 	if (phydev->duplex != DUPLEX_FULL)
 		return -EINVAL;
 
 	ctrl1 = phy_read_mmd(phydev, MDIO_MMD_PMAPMD, MDIO_CTRL1);
 	if (ctrl1 < 0)
 		return ctrl1;
 
 	ctrl2 = phy_read_mmd(phydev, MDIO_MMD_PMAPMD, MDIO_CTRL2);
 	if (ctrl2 < 0)
 		return ctrl2;
 
 	ctrl1 &= ~MDIO_CTRL1_SPEEDSEL;
 	/*
diff --git a/drivers/net/phy/phy.c b/drivers/net/phy/phy.c
index 477bdf2f94df..dce86bad8231 100644
--- a/drivers/net/phy/phy.c
+++ b/drivers/net/phy/phy.c
@@ -472,41 +472,41 @@ int phy_do_ioctl_running(struct net_device *dev, struct ifreq *ifr, int cmd)
 		return -ENODEV;
 
 	return phy_do_ioctl(dev, ifr, cmd);
 }
 EXPORT_SYMBOL(phy_do_ioctl_running);
 
 /**
  * phy_queue_state_machine - Trigger the state machine to run soon
  *
  * @phydev: the phy_device struct
  * @jiffies: Run the state machine after these jiffies
  */
 void phy_queue_state_machine(struct phy_device *phydev, unsigned long jiffies)
 {
 	mod_delayed_work(system_power_efficient_wq, &phydev->state_queue,
 			 jiffies);
 }
 EXPORT_SYMBOL(phy_queue_state_machine);
 
 /**
- * phy_queue_state_machine - Trigger the state machine to run now
+ * phy_trigger_machine - Trigger the state machine to run now
  *
  * @phydev: the phy_device struct
  */
 void phy_trigger_machine(struct phy_device *phydev)
 {
 	phy_queue_state_machine(phydev, 0);
 }
 EXPORT_SYMBOL(phy_trigger_machine);
 
 static void phy_abort_cable_test(struct phy_device *phydev)
 {
 	int err;
 
 	ethnl_cable_test_finished(phydev);
 
 	err = phy_init_hw(phydev);
 	if (err)
 		phydev_err(phydev, "Error while aborting cable test");
 }
 
diff --git a/drivers/net/phy/phy_device.c b/drivers/net/phy/phy_device.c
index e13a46c25437..8f34bedceadc 100644
--- a/drivers/net/phy/phy_device.c
+++ b/drivers/net/phy/phy_device.c
@@ -2731,41 +2731,41 @@ EXPORT_SYMBOL(phy_get_pause);
 #if IS_ENABLED(CONFIG_OF_MDIO)
 static int phy_get_int_delay_property(struct device *dev, const char *name)
 {
 	s32 int_delay;
 	int ret;
 
 	ret = device_property_read_u32(dev, name, &int_delay);
 	if (ret)
 		return ret;
 
 	return int_delay;
 }
 #else
 static int phy_get_int_delay_property(struct device *dev, const char *name)
 {
 	return -EINVAL;
 }
 #endif
 
 /**
- * phy_get_delay_index - returns the index of the internal delay
+ * phy_get_internal_delay - returns the index of the internal delay
  * @phydev: phy_device struct
  * @dev: pointer to the devices device struct
  * @delay_values: array of delays the PHY supports
  * @size: the size of the delay array
  * @is_rx: boolean to indicate to get the rx internal delay
  *
  * Returns the index within the array of internal delay passed in.
  * If the device property is not present then the interface type is checked
  * if the interface defines use of internal delay then a 1 is returned otherwise
  * a 0 is returned.
  * The array must be in ascending order. If PHY does not have an ascending order
  * array then size = 0 and the value of the delay property is returned.
  * Return -EINVAL if the delay is invalid or cannot be found.
  */
 s32 phy_get_internal_delay(struct phy_device *phydev, struct device *dev,
 			   const int *delay_values, int size, bool is_rx)
 {
 	s32 delay;
 	int i;
 
diff --git a/drivers/net/phy/phylink.c b/drivers/net/phy/phylink.c
index 5d8c015bc9f2..84f6e197f965 100644
--- a/drivers/net/phy/phylink.c
+++ b/drivers/net/phy/phylink.c
@@ -1632,41 +1632,41 @@ int phylink_ethtool_set_pauseparam(struct phylink *pl,
 	 * we can't hold our state mutex while calling phy_set_asym_pause().
 	 */
 	if (pl->phydev)
 		phy_set_asym_pause(pl->phydev, pause->rx_pause,
 				   pause->tx_pause);
 
 	/* If the manual pause settings changed, make sure we trigger a
 	 * resolve to update their state; we can not guarantee that the
 	 * link will cycle.
 	 */
 	if (manual_changed) {
 		pl->mac_link_dropped = true;
 		phylink_run_resolve(pl);
 	}
 
 	return 0;
 }
 EXPORT_SYMBOL_GPL(phylink_ethtool_set_pauseparam);
 
 /**
- * phylink_ethtool_get_eee_err() - read the energy efficient ethernet error
+ * phylink_get_eee_err() - read the energy efficient ethernet error
  *   counter
  * @pl: a pointer to a &struct phylink returned from phylink_create().
  *
  * Read the Energy Efficient Ethernet error counter from the PHY associated
  * with the phylink instance specified by @pl.
  *
  * Returns positive error counter value, or negative error code.
  */
 int phylink_get_eee_err(struct phylink *pl)
 {
 	int ret = 0;
 
 	ASSERT_RTNL();
 
 	if (pl->phydev)
 		ret = phy_get_eee_err(pl->phydev);
 
 	return ret;
 }
 EXPORT_SYMBOL_GPL(phylink_get_eee_err);
-- 
2.28.0

[PATCH v4 02/27] net: datagram: fix some kernel-doc markups

[Mauro Carvalho Chehab]

Some identifiers have different names between their prototypes
and the kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 net/core/datagram.c   | 2 +-
 net/core/dev.c        | 4 ++--
 net/core/skbuff.c     | 2 +-
 net/ethernet/eth.c    | 6 +++---
 net/sunrpc/rpc_pipe.c | 3 ++-
 5 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/net/core/datagram.c b/net/core/datagram.c
index 9fcaa544f11a..81809fa735a7 100644
--- a/net/core/datagram.c
+++ b/net/core/datagram.c
@@ -692,41 +692,41 @@ EXPORT_SYMBOL(__zerocopy_sg_from_iter);
  *	@from: the source to copy from
  *
  *	The function will first copy up to headlen, and then pin the userspace
  *	pages and build frags through them.
  *
  *	Returns 0, -EFAULT or -EMSGSIZE.
  */
 int zerocopy_sg_from_iter(struct sk_buff *skb, struct iov_iter *from)
 {
 	int copy = min_t(int, skb_headlen(skb), iov_iter_count(from));
 
 	/* copy up to skb headlen */
 	if (skb_copy_datagram_from_iter(skb, 0, from, copy))
 		return -EFAULT;
 
 	return __zerocopy_sg_from_iter(NULL, skb, from, ~0U);
 }
 EXPORT_SYMBOL(zerocopy_sg_from_iter);
 
 /**
- *	skb_copy_and_csum_datagram_iter - Copy datagram to an iovec iterator
+ *	skb_copy_and_csum_datagram - Copy datagram to an iovec iterator
  *          and update a checksum.
  *	@skb: buffer to copy
  *	@offset: offset in the buffer to start copying from
  *	@to: iovec iterator to copy to
  *	@len: amount of data to copy from buffer to iovec
  *      @csump: checksum pointer
  */
 static int skb_copy_and_csum_datagram(const struct sk_buff *skb, int offset,
 				      struct iov_iter *to, int len,
 				      __wsum *csump)
 {
 	return __skb_datagram_iter(skb, offset, to, len, true,
 			csum_and_copy_to_iter, csump);
 }
 
 /**
  *	skb_copy_and_csum_datagram_msg - Copy and checksum skb to user iovec.
  *	@skb: skbuff
  *	@hlen: hardware length
  *	@msg: destination
diff --git a/net/core/dev.c b/net/core/dev.c
index 60d325bda0d7..4bfdcd6b20e8 100644
--- a/net/core/dev.c
+++ b/net/core/dev.c
@@ -6902,41 +6902,41 @@ static int ____netdev_has_upper_dev(struct net_device *upper_dev,
  *
  * Find out if a device is linked to specified upper device and return true
  * in case it is. Note that this checks only immediate upper device,
  * not through a complete stack of devices. The caller must hold the RTNL lock.
  */
 bool netdev_has_upper_dev(struct net_device *dev,
 			  struct net_device *upper_dev)
 {
 	struct netdev_nested_priv priv = {
 		.data = (void *)upper_dev,
 	};
 
 	ASSERT_RTNL();
 
 	return netdev_walk_all_upper_dev_rcu(dev, ____netdev_has_upper_dev,
 					     &priv);
 }
 EXPORT_SYMBOL(netdev_has_upper_dev);
 
 /**
- * netdev_has_upper_dev_all - Check if device is linked to an upper device
+ * netdev_has_upper_dev_all_rcu - Check if device is linked to an upper device
  * @dev: device
  * @upper_dev: upper device to check
  *
  * Find out if a device is linked to specified upper device and return true
  * in case it is. Note that this checks the entire upper device chain.
  * The caller must hold rcu lock.
  */
 
 bool netdev_has_upper_dev_all_rcu(struct net_device *dev,
 				  struct net_device *upper_dev)
 {
 	struct netdev_nested_priv priv = {
 		.data = (void *)upper_dev,
 	};
 
 	return !!netdev_walk_all_upper_dev_rcu(dev, ____netdev_has_upper_dev,
 					       &priv);
 }
 EXPORT_SYMBOL(netdev_has_upper_dev_all_rcu);
 
@@ -8140,41 +8140,41 @@ void netdev_adjacent_rename_links(struct net_device *dev, char *oldname)
 	}
 }
 
 void *netdev_lower_dev_get_private(struct net_device *dev,
 				   struct net_device *lower_dev)
 {
 	struct netdev_adjacent *lower;
 
 	if (!lower_dev)
 		return NULL;
 	lower = __netdev_find_adj(lower_dev, &dev->adj_list.lower);
 	if (!lower)
 		return NULL;
 
 	return lower->private;
 }
 EXPORT_SYMBOL(netdev_lower_dev_get_private);
 
 
 /**
- * netdev_lower_change - Dispatch event about lower device state change
+ * netdev_lower_state_changed - Dispatch event about lower device state change
  * @lower_dev: device
  * @lower_state_info: state to dispatch
  *
  * Send NETDEV_CHANGELOWERSTATE to netdev notifiers with info.
  * The caller must hold the RTNL lock.
  */
 void netdev_lower_state_changed(struct net_device *lower_dev,
 				void *lower_state_info)
 {
 	struct netdev_notifier_changelowerstate_info changelowerstate_info = {
 		.info.dev = lower_dev,
 	};
 
 	ASSERT_RTNL();
 	changelowerstate_info.lower_state_info = lower_state_info;
 	call_netdevice_notifiers_info(NETDEV_CHANGELOWERSTATE,
 				      &changelowerstate_info.info);
 }
 EXPORT_SYMBOL(netdev_lower_state_changed);
 
diff --git a/net/core/skbuff.c b/net/core/skbuff.c
index c9a5a3c262c8..ffe3dcc0ebea 100644
--- a/net/core/skbuff.c
+++ b/net/core/skbuff.c
@@ -825,41 +825,41 @@ EXPORT_SYMBOL(skb_tx_error);
 /**
  *	consume_skb - free an skbuff
  *	@skb: buffer to free
  *
  *	Drop a ref to the buffer and free it if the usage count has hit zero
  *	Functions identically to kfree_skb, but kfree_skb assumes that the frame
  *	is being dropped after a failure and notes that
  */
 void consume_skb(struct sk_buff *skb)
 {
 	if (!skb_unref(skb))
 		return;
 
 	trace_consume_skb(skb);
 	__kfree_skb(skb);
 }
 EXPORT_SYMBOL(consume_skb);
 #endif
 
 /**
- *	consume_stateless_skb - free an skbuff, assuming it is stateless
+ *	__consume_stateless_skb - free an skbuff, assuming it is stateless
  *	@skb: buffer to free
  *
  *	Alike consume_skb(), but this variant assumes that this is the last
  *	skb reference and all the head states have been already dropped
  */
 void __consume_stateless_skb(struct sk_buff *skb)
 {
 	trace_consume_skb(skb);
 	skb_release_data(skb);
 	kfree_skbmem(skb);
 }
 
 void __kfree_skb_flush(void)
 {
 	struct napi_alloc_cache *nc = this_cpu_ptr(&napi_alloc_cache);
 
 	/* flush skb_cache if containing objects */
 	if (nc->skb_count) {
 		kmem_cache_free_bulk(skbuff_head_cache, nc->skb_count,
 				     nc->skb_cache);
diff --git a/net/ethernet/eth.c b/net/ethernet/eth.c
index dac65180c4ef..4106373180c6 100644
--- a/net/ethernet/eth.c
+++ b/net/ethernet/eth.c
@@ -255,41 +255,41 @@ int eth_header_cache(const struct neighbour *neigh, struct hh_cache *hh, __be16
 EXPORT_SYMBOL(eth_header_cache);
 
 /**
  * eth_header_cache_update - update cache entry
  * @hh: destination cache entry
  * @dev: network device
  * @haddr: new hardware address
  *
  * Called by Address Resolution module to notify changes in address.
  */
 void eth_header_cache_update(struct hh_cache *hh,
 			     const struct net_device *dev,
 			     const unsigned char *haddr)
 {
 	memcpy(((u8 *) hh->hh_data) + HH_DATA_OFF(sizeof(struct ethhdr)),
 	       haddr, ETH_ALEN);
 }
 EXPORT_SYMBOL(eth_header_cache_update);
 
 /**
- * eth_header_parser_protocol - extract protocol from L2 header
+ * eth_header_parse_protocol - extract protocol from L2 header
  * @skb: packet to extract protocol from
  */
 __be16 eth_header_parse_protocol(const struct sk_buff *skb)
 {
 	const struct ethhdr *eth = eth_hdr(skb);
 
 	return eth->h_proto;
 }
 EXPORT_SYMBOL(eth_header_parse_protocol);
 
 /**
  * eth_prepare_mac_addr_change - prepare for mac change
  * @dev: network device
  * @p: socket address
  */
 int eth_prepare_mac_addr_change(struct net_device *dev, void *p)
 {
 	struct sockaddr *addr = p;
 
 	if (!(dev->priv_flags & IFF_LIVE_ADDR_CHANGE) && netif_running(dev))
@@ -506,42 +506,42 @@ unsigned char * __weak arch_get_platform_mac_address(void)
 
 int eth_platform_get_mac_address(struct device *dev, u8 *mac_addr)
 {
 	const unsigned char *addr = NULL;
 
 	if (dev->of_node)
 		addr = of_get_mac_address(dev->of_node);
 	if (IS_ERR_OR_NULL(addr))
 		addr = arch_get_platform_mac_address();
 
 	if (!addr)
 		return -ENODEV;
 
 	ether_addr_copy(mac_addr, addr);
 
 	return 0;
 }
 EXPORT_SYMBOL(eth_platform_get_mac_address);
 
 /**
- * Obtain the MAC address from an nvmem cell named 'mac-address' associated
- * with given device.
+ * nvmem_get_mac_address - Obtain the MAC address from an nvmem cell named
+ * 'mac-address' associated with given device.
  *
  * @dev:	Device with which the mac-address cell is associated.
  * @addrbuf:	Buffer to which the MAC address will be copied on success.
  *
  * Returns 0 on success or a negative error number on failure.
  */
 int nvmem_get_mac_address(struct device *dev, void *addrbuf)
 {
 	struct nvmem_cell *cell;
 	const void *mac;
 	size_t len;
 
 	cell = nvmem_cell_get(dev, "mac-address");
 	if (IS_ERR(cell))
 		return PTR_ERR(cell);
 
 	mac = nvmem_cell_read(cell, &len);
 	nvmem_cell_put(cell);
 
 	if (IS_ERR(mac))
diff --git a/net/sunrpc/rpc_pipe.c b/net/sunrpc/rpc_pipe.c
index eadc0ede928c..8241f5a4a01c 100644
--- a/net/sunrpc/rpc_pipe.c
+++ b/net/sunrpc/rpc_pipe.c
@@ -764,41 +764,42 @@ static struct dentry *rpc_mkdir_populate(struct dentry *parent,
 
 static int rpc_rmdir_depopulate(struct dentry *dentry,
 		void (*depopulate)(struct dentry *))
 {
 	struct dentry *parent;
 	struct inode *dir;
 	int error;
 
 	parent = dget_parent(dentry);
 	dir = d_inode(parent);
 	inode_lock_nested(dir, I_MUTEX_PARENT);
 	if (depopulate != NULL)
 		depopulate(dentry);
 	error = __rpc_rmdir(dir, dentry);
 	inode_unlock(dir);
 	dput(parent);
 	return error;
 }
 
 /**
- * rpc_mkpipe - make an rpc_pipefs file for kernel<->userspace communication
+ * rpc_mkpipe_dentry - make an rpc_pipefs file for kernel<->userspace
+ *		       communication
  * @parent: dentry of directory to create new "pipe" in
  * @name: name of pipe
  * @private: private data to associate with the pipe, for the caller's use
  * @pipe: &rpc_pipe containing input parameters
  *
  * Data is made available for userspace to read by calls to
  * rpc_queue_upcall().  The actual reads will result in calls to
  * @ops->upcall, which will be called with the file pointer,
  * message, and userspace buffer to copy to.
  *
  * Writes can come at any time, and do not necessarily have to be
  * responses to upcalls.  They will result in calls to @msg->downcall.
  *
  * The @private argument passed here will be available to all these methods
  * from the file pointer, via RPC_I(file_inode(file))->private.
  */
 struct dentry *rpc_mkpipe_dentry(struct dentry *parent, const char *name,
 				 void *private, struct rpc_pipe *pipe)
 {
 	struct dentry *dentry;
-- 
2.28.0

[PATCH v4 03/27] net: core: fix some kernel-doc markups

[Mauro Carvalho Chehab]

Some identifiers have different names between their prototypes
and the kernel-doc markup.

In the specific case of netif_subqueue_stopped(), keep the
current markup for __netif_subqueue_stopped(), adding a
new one for netif_subqueue_stopped().

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/netdevice.h | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
index 7ce648a564f7..03433a4c929e 100644
--- a/include/linux/netdevice.h
+++ b/include/linux/netdevice.h
@@ -1473,41 +1473,41 @@ struct net_device_ops {
 	int			(*ndo_change_proto_down)(struct net_device *dev,
 							 bool proto_down);
 	int			(*ndo_fill_metadata_dst)(struct net_device *dev,
 						       struct sk_buff *skb);
 	void			(*ndo_set_rx_headroom)(struct net_device *dev,
 						       int needed_headroom);
 	int			(*ndo_bpf)(struct net_device *dev,
 					   struct netdev_bpf *bpf);
 	int			(*ndo_xdp_xmit)(struct net_device *dev, int n,
 						struct xdp_frame **xdp,
 						u32 flags);
 	int			(*ndo_xsk_wakeup)(struct net_device *dev,
 						  u32 queue_id, u32 flags);
 	struct devlink_port *	(*ndo_get_devlink_port)(struct net_device *dev);
 	int			(*ndo_tunnel_ctl)(struct net_device *dev,
 						  struct ip_tunnel_parm *p, int cmd);
 	struct net_device *	(*ndo_get_peer_dev)(struct net_device *dev);
 };
 
 /**
- * enum net_device_priv_flags - &struct net_device priv_flags
+ * enum netdev_priv_flags - &struct net_device priv_flags
  *
  * These are the &struct net_device, they are only set internally
  * by drivers and used in the kernel. These flags are invisible to
  * userspace; this means that the order of these flags can change
  * during any kernel release.
  *
  * You should have a pretty good reason to be extending these flags.
  *
  * @IFF_802_1Q_VLAN: 802.1Q VLAN device
  * @IFF_EBRIDGE: Ethernet bridging device
  * @IFF_BONDING: bonding master or slave
  * @IFF_ISATAP: ISATAP interface (RFC4214)
  * @IFF_WAN_HDLC: WAN HDLC device
  * @IFF_XMIT_DST_RELEASE: dev_hard_start_xmit() is allowed to
  *	release skb->dst
  * @IFF_DONT_BRIDGE: disallow bridging this ether dev
  * @IFF_DISABLE_NETPOLL: disable netpoll at run-time
  * @IFF_MACVLAN_PORT: device used as macvlan port
  * @IFF_BRIDGE_PORT: device used as bridge port
  * @IFF_OVS_DATAPATH: device used as Open vSwitch datapath port
@@ -3585,54 +3585,61 @@ static inline void netif_start_subqueue(struct net_device *dev, u16 queue_index)
 {
 	struct netdev_queue *txq = netdev_get_tx_queue(dev, queue_index);
 
 	netif_tx_start_queue(txq);
 }
 
 /**
  *	netif_stop_subqueue - stop sending packets on subqueue
  *	@dev: network device
  *	@queue_index: sub queue index
  *
  * Stop individual transmit queue of a device with multiple transmit queues.
  */
 static inline void netif_stop_subqueue(struct net_device *dev, u16 queue_index)
 {
 	struct netdev_queue *txq = netdev_get_tx_queue(dev, queue_index);
 	netif_tx_stop_queue(txq);
 }
 
 /**
- *	netif_subqueue_stopped - test status of subqueue
+ *	__netif_subqueue_stopped - test status of subqueue
  *	@dev: network device
  *	@queue_index: sub queue index
  *
  * Check individual transmit queue of a device with multiple transmit queues.
  */
 static inline bool __netif_subqueue_stopped(const struct net_device *dev,
 					    u16 queue_index)
 {
 	struct netdev_queue *txq = netdev_get_tx_queue(dev, queue_index);
 
 	return netif_tx_queue_stopped(txq);
 }
 
+/**
+ *	netif_subqueue_stopped - test status of subqueue
+ *	@dev: network device
+ *	@skb: sub queue buffer pointer
+ *
+ * Check individual transmit queue of a device with multiple transmit queues.
+ */
 static inline bool netif_subqueue_stopped(const struct net_device *dev,
 					  struct sk_buff *skb)
 {
 	return __netif_subqueue_stopped(dev, skb_get_queue_mapping(skb));
 }
 
 /**
  *	netif_wake_subqueue - allow sending packets on subqueue
  *	@dev: network device
  *	@queue_index: sub queue index
  *
  * Resume individual transmit queue of a device with multiple transmit queues.
  */
 static inline void netif_wake_subqueue(struct net_device *dev, u16 queue_index)
 {
 	struct netdev_queue *txq = netdev_get_tx_queue(dev, queue_index);
 
 	netif_tx_wake_queue(txq);
 }
 
-- 
2.28.0

Re: [PATCH v4 02/27] net: datagram: fix some kernel-doc markups

[Kirill Tkhai]

On 16.11.2020 13:17, Mauro Carvalho Chehab wrote:
> Some identifiers have different names between their prototypes
> and the kernel-doc markup.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Reviewed-by: Kirill Tkhai <ktkhai@virtuozzo.com>

> ---
>  net/core/datagram.c   | 2 +-
>  net/core/dev.c        | 4 ++--
>  net/core/skbuff.c     | 2 +-
>  net/ethernet/eth.c    | 6 +++---
>  net/sunrpc/rpc_pipe.c | 3 ++-
>  5 files changed, 9 insertions(+), 8 deletions(-)
> 
> diff --git a/net/core/datagram.c b/net/core/datagram.c
> index 9fcaa544f11a..81809fa735a7 100644
> --- a/net/core/datagram.c
> +++ b/net/core/datagram.c
> @@ -692,41 +692,41 @@ EXPORT_SYMBOL(__zerocopy_sg_from_iter);
>   *	@from: the source to copy from
>   *
>   *	The function will first copy up to headlen, and then pin the userspace
>   *	pages and build frags through them.
>   *
>   *	Returns 0, -EFAULT or -EMSGSIZE.
>   */
>  int zerocopy_sg_from_iter(struct sk_buff *skb, struct iov_iter *from)
>  {
>  	int copy = min_t(int, skb_headlen(skb), iov_iter_count(from));
>  
>  	/* copy up to skb headlen */
>  	if (skb_copy_datagram_from_iter(skb, 0, from, copy))
>  		return -EFAULT;
>  
>  	return __zerocopy_sg_from_iter(NULL, skb, from, ~0U);
>  }
>  EXPORT_SYMBOL(zerocopy_sg_from_iter);
>  
>  /**
> - *	skb_copy_and_csum_datagram_iter - Copy datagram to an iovec iterator
> + *	skb_copy_and_csum_datagram - Copy datagram to an iovec iterator
>   *          and update a checksum.
>   *	@skb: buffer to copy
>   *	@offset: offset in the buffer to start copying from
>   *	@to: iovec iterator to copy to
>   *	@len: amount of data to copy from buffer to iovec
>   *      @csump: checksum pointer
>   */
>  static int skb_copy_and_csum_datagram(const struct sk_buff *skb, int offset,
>  				      struct iov_iter *to, int len,
>  				      __wsum *csump)
>  {
>  	return __skb_datagram_iter(skb, offset, to, len, true,
>  			csum_and_copy_to_iter, csump);
>  }
>  
>  /**
>   *	skb_copy_and_csum_datagram_msg - Copy and checksum skb to user iovec.
>   *	@skb: skbuff
>   *	@hlen: hardware length
>   *	@msg: destination
> diff --git a/net/core/dev.c b/net/core/dev.c
> index 60d325bda0d7..4bfdcd6b20e8 100644
> --- a/net/core/dev.c
> +++ b/net/core/dev.c
> @@ -6902,41 +6902,41 @@ static int ____netdev_has_upper_dev(struct net_device *upper_dev,
>   *
>   * Find out if a device is linked to specified upper device and return true
>   * in case it is. Note that this checks only immediate upper device,
>   * not through a complete stack of devices. The caller must hold the RTNL lock.
>   */
>  bool netdev_has_upper_dev(struct net_device *dev,
>  			  struct net_device *upper_dev)
>  {
>  	struct netdev_nested_priv priv = {
>  		.data = (void *)upper_dev,
>  	};
>  
>  	ASSERT_RTNL();
>  
>  	return netdev_walk_all_upper_dev_rcu(dev, ____netdev_has_upper_dev,
>  					     &priv);
>  }
>  EXPORT_SYMBOL(netdev_has_upper_dev);
>  
>  /**
> - * netdev_has_upper_dev_all - Check if device is linked to an upper device
> + * netdev_has_upper_dev_all_rcu - Check if device is linked to an upper device
>   * @dev: device
>   * @upper_dev: upper device to check
>   *
>   * Find out if a device is linked to specified upper device and return true
>   * in case it is. Note that this checks the entire upper device chain.
>   * The caller must hold rcu lock.
>   */
>  
>  bool netdev_has_upper_dev_all_rcu(struct net_device *dev,
>  				  struct net_device *upper_dev)
>  {
>  	struct netdev_nested_priv priv = {
>  		.data = (void *)upper_dev,
>  	};
>  
>  	return !!netdev_walk_all_upper_dev_rcu(dev, ____netdev_has_upper_dev,
>  					       &priv);
>  }
>  EXPORT_SYMBOL(netdev_has_upper_dev_all_rcu);
>  
> @@ -8140,41 +8140,41 @@ void netdev_adjacent_rename_links(struct net_device *dev, char *oldname)
>  	}
>  }
>  
>  void *netdev_lower_dev_get_private(struct net_device *dev,
>  				   struct net_device *lower_dev)
>  {
>  	struct netdev_adjacent *lower;
>  
>  	if (!lower_dev)
>  		return NULL;
>  	lower = __netdev_find_adj(lower_dev, &dev->adj_list.lower);
>  	if (!lower)
>  		return NULL;
>  
>  	return lower->private;
>  }
>  EXPORT_SYMBOL(netdev_lower_dev_get_private);
>  
>  
>  /**
> - * netdev_lower_change - Dispatch event about lower device state change
> + * netdev_lower_state_changed - Dispatch event about lower device state change
>   * @lower_dev: device
>   * @lower_state_info: state to dispatch
>   *
>   * Send NETDEV_CHANGELOWERSTATE to netdev notifiers with info.
>   * The caller must hold the RTNL lock.
>   */
>  void netdev_lower_state_changed(struct net_device *lower_dev,
>  				void *lower_state_info)
>  {
>  	struct netdev_notifier_changelowerstate_info changelowerstate_info = {
>  		.info.dev = lower_dev,
>  	};
>  
>  	ASSERT_RTNL();
>  	changelowerstate_info.lower_state_info = lower_state_info;
>  	call_netdevice_notifiers_info(NETDEV_CHANGELOWERSTATE,
>  				      &changelowerstate_info.info);
>  }
>  EXPORT_SYMBOL(netdev_lower_state_changed);
>  
> diff --git a/net/core/skbuff.c b/net/core/skbuff.c
> index c9a5a3c262c8..ffe3dcc0ebea 100644
> --- a/net/core/skbuff.c
> +++ b/net/core/skbuff.c
> @@ -825,41 +825,41 @@ EXPORT_SYMBOL(skb_tx_error);
>  /**
>   *	consume_skb - free an skbuff
>   *	@skb: buffer to free
>   *
>   *	Drop a ref to the buffer and free it if the usage count has hit zero
>   *	Functions identically to kfree_skb, but kfree_skb assumes that the frame
>   *	is being dropped after a failure and notes that
>   */
>  void consume_skb(struct sk_buff *skb)
>  {
>  	if (!skb_unref(skb))
>  		return;
>  
>  	trace_consume_skb(skb);
>  	__kfree_skb(skb);
>  }
>  EXPORT_SYMBOL(consume_skb);
>  #endif
>  
>  /**
> - *	consume_stateless_skb - free an skbuff, assuming it is stateless
> + *	__consume_stateless_skb - free an skbuff, assuming it is stateless
>   *	@skb: buffer to free
>   *
>   *	Alike consume_skb(), but this variant assumes that this is the last
>   *	skb reference and all the head states have been already dropped
>   */
>  void __consume_stateless_skb(struct sk_buff *skb)
>  {
>  	trace_consume_skb(skb);
>  	skb_release_data(skb);
>  	kfree_skbmem(skb);
>  }
>  
>  void __kfree_skb_flush(void)
>  {
>  	struct napi_alloc_cache *nc = this_cpu_ptr(&napi_alloc_cache);
>  
>  	/* flush skb_cache if containing objects */
>  	if (nc->skb_count) {
>  		kmem_cache_free_bulk(skbuff_head_cache, nc->skb_count,
>  				     nc->skb_cache);
> diff --git a/net/ethernet/eth.c b/net/ethernet/eth.c
> index dac65180c4ef..4106373180c6 100644
> --- a/net/ethernet/eth.c
> +++ b/net/ethernet/eth.c
> @@ -255,41 +255,41 @@ int eth_header_cache(const struct neighbour *neigh, struct hh_cache *hh, __be16
>  EXPORT_SYMBOL(eth_header_cache);
>  
>  /**
>   * eth_header_cache_update - update cache entry
>   * @hh: destination cache entry
>   * @dev: network device
>   * @haddr: new hardware address
>   *
>   * Called by Address Resolution module to notify changes in address.
>   */
>  void eth_header_cache_update(struct hh_cache *hh,
>  			     const struct net_device *dev,
>  			     const unsigned char *haddr)
>  {
>  	memcpy(((u8 *) hh->hh_data) + HH_DATA_OFF(sizeof(struct ethhdr)),
>  	       haddr, ETH_ALEN);
>  }
>  EXPORT_SYMBOL(eth_header_cache_update);
>  
>  /**
> - * eth_header_parser_protocol - extract protocol from L2 header
> + * eth_header_parse_protocol - extract protocol from L2 header
>   * @skb: packet to extract protocol from
>   */
>  __be16 eth_header_parse_protocol(const struct sk_buff *skb)
>  {
>  	const struct ethhdr *eth = eth_hdr(skb);
>  
>  	return eth->h_proto;
>  }
>  EXPORT_SYMBOL(eth_header_parse_protocol);
>  
>  /**
>   * eth_prepare_mac_addr_change - prepare for mac change
>   * @dev: network device
>   * @p: socket address
>   */
>  int eth_prepare_mac_addr_change(struct net_device *dev, void *p)
>  {
>  	struct sockaddr *addr = p;
>  
>  	if (!(dev->priv_flags & IFF_LIVE_ADDR_CHANGE) && netif_running(dev))
> @@ -506,42 +506,42 @@ unsigned char * __weak arch_get_platform_mac_address(void)
>  
>  int eth_platform_get_mac_address(struct device *dev, u8 *mac_addr)
>  {
>  	const unsigned char *addr = NULL;
>  
>  	if (dev->of_node)
>  		addr = of_get_mac_address(dev->of_node);
>  	if (IS_ERR_OR_NULL(addr))
>  		addr = arch_get_platform_mac_address();
>  
>  	if (!addr)
>  		return -ENODEV;
>  
>  	ether_addr_copy(mac_addr, addr);
>  
>  	return 0;
>  }
>  EXPORT_SYMBOL(eth_platform_get_mac_address);
>  
>  /**
> - * Obtain the MAC address from an nvmem cell named 'mac-address' associated
> - * with given device.
> + * nvmem_get_mac_address - Obtain the MAC address from an nvmem cell named
> + * 'mac-address' associated with given device.
>   *
>   * @dev:	Device with which the mac-address cell is associated.
>   * @addrbuf:	Buffer to which the MAC address will be copied on success.
>   *
>   * Returns 0 on success or a negative error number on failure.
>   */
>  int nvmem_get_mac_address(struct device *dev, void *addrbuf)
>  {
>  	struct nvmem_cell *cell;
>  	const void *mac;
>  	size_t len;
>  
>  	cell = nvmem_cell_get(dev, "mac-address");
>  	if (IS_ERR(cell))
>  		return PTR_ERR(cell);
>  
>  	mac = nvmem_cell_read(cell, &len);
>  	nvmem_cell_put(cell);
>  
>  	if (IS_ERR(mac))
> diff --git a/net/sunrpc/rpc_pipe.c b/net/sunrpc/rpc_pipe.c
> index eadc0ede928c..8241f5a4a01c 100644
> --- a/net/sunrpc/rpc_pipe.c
> +++ b/net/sunrpc/rpc_pipe.c
> @@ -764,41 +764,42 @@ static struct dentry *rpc_mkdir_populate(struct dentry *parent,
>  
>  static int rpc_rmdir_depopulate(struct dentry *dentry,
>  		void (*depopulate)(struct dentry *))
>  {
>  	struct dentry *parent;
>  	struct inode *dir;
>  	int error;
>  
>  	parent = dget_parent(dentry);
>  	dir = d_inode(parent);
>  	inode_lock_nested(dir, I_MUTEX_PARENT);
>  	if (depopulate != NULL)
>  		depopulate(dentry);
>  	error = __rpc_rmdir(dir, dentry);
>  	inode_unlock(dir);
>  	dput(parent);
>  	return error;
>  }
>  
>  /**
> - * rpc_mkpipe - make an rpc_pipefs file for kernel<->userspace communication
> + * rpc_mkpipe_dentry - make an rpc_pipefs file for kernel<->userspace
> + *		       communication
>   * @parent: dentry of directory to create new "pipe" in
>   * @name: name of pipe
>   * @private: private data to associate with the pipe, for the caller's use
>   * @pipe: &rpc_pipe containing input parameters
>   *
>   * Data is made available for userspace to read by calls to
>   * rpc_queue_upcall().  The actual reads will result in calls to
>   * @ops->upcall, which will be called with the file pointer,
>   * message, and userspace buffer to copy to.
>   *
>   * Writes can come at any time, and do not necessarily have to be
>   * responses to upcalls.  They will result in calls to @msg->downcall.
>   *
>   * The @private argument passed here will be available to all these methods
>   * from the file pointer, via RPC_I(file_inode(file))->private.
>   */
>  struct dentry *rpc_mkpipe_dentry(struct dentry *parent, const char *name,
>  				 void *private, struct rpc_pipe *pipe)
>  {
>  	struct dentry *dentry;
> 

Re: [PATCH v4 00/27]Fix several bad kernel-doc markups

[Jakub Kicinski]

On Mon, 16 Nov 2020 11:17:56 +0100 Mauro Carvalho Chehab wrote:
> Kernel-doc has always be limited to a probably bad documented
> rule:
> 
> The kernel-doc markups should appear *imediatelly before* the
> function or data structure that it documents.

Applied 1-3 to net-next, thanks!