linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH v4 00/27]Fix several bad kernel-doc markups
@ 2020-11-16 10:17 Mauro Carvalho Chehab
  2020-11-16 10:17 ` [PATCH v4 01/27] net: phy: fix " Mauro Carvalho Chehab
                   ` (27 more replies)
  0 siblings, 28 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:17 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
	David S. Miller, Theodore Ts'o, Alexander Viro,
	Alexandre Bounine, Andrew Lunn, Andrew Morton, Andy Lutomirski,
	Anna Schumaker, Anton Vorontsov, Ben Segall, Colin Cross,
	Daniel Bristot de Oliveira, Daniel Vetter, David Airlie,
	Dietmar Eggemann, Evgeniy Polyakov, Heiner Kallweit, Ingo Molnar,
	Jakub Kicinski, Jan Kara, Juri Lelli, Kees Cook,
	Maarten Lankhorst, Matt Porter, Maxime Ripard, Mel Gorman,
	Mike Rapoport, Peter Zijlstra, Richard Gong, Russell King,
	Sebastian Reichel, Shuah Khan, Steven Rostedt, Sudip Mukherjee,
	Thomas Gleixner, Thomas Zimmermann, Tony Luck, Trond Myklebust,
	Vincent Guittot, Will Drewry, dri-devel, intel-gfx, linux-ext4,
	linux-fbdev, linux-fsdevel, linux-kselftest, linux-mm, linux-nfs,
	linux-rdma, linux-s390, netdev, target-devel

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



^ permalink raw reply	[flat|nested] 51+ messages in thread

* [PATCH v4 01/27] net: phy: fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
@ 2020-11-16 10:17 ` Mauro Carvalho Chehab
  2020-11-16 10:17 ` [PATCH v4 02/27] net: datagram: fix some " Mauro Carvalho Chehab
                   ` (26 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:17 UTC (permalink / raw)
  To: David S. Miller, Andrew Lunn, Heiner Kallweit, Jakub Kicinski
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	Russell King, linux-kernel, netdev

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


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 02/27] net: datagram: fix some kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
  2020-11-16 10:17 ` [PATCH v4 01/27] net: phy: fix " Mauro Carvalho Chehab
@ 2020-11-16 10:17 ` Mauro Carvalho Chehab
  2020-11-16 10:20   ` Kirill Tkhai
  2020-11-16 10:17 ` [PATCH v4 03/27] net: core: " Mauro Carvalho Chehab
                   ` (25 subsequent siblings)
  27 siblings, 1 reply; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:17 UTC (permalink / raw)
  To: Anna Schumaker, Trond Myklebust
  Cc: Mauro Carvalho Chehab, David S. Miller, J. Bruce Fields,
	Jonathan Corbet, Linux Doc Mailing List, Al Viro,
	Alexei Starovoitov, Andrii Nakryiko, Bartosz Golaszewski,
	Chuck Lever, Cong Wang, Eric Dumazet, Florian Westphal,
	Guillaume Nault, Heiner Kallweit, Jakub Kicinski, Jiri Pirko,
	Kirill Tkhai, Martin Varghese, Maxim Mikityanskiy, Miaohe Lin,
	Paolo Abeni, Pravin B Shelar, Sabrina Dubroca, Steffen Klassert,
	Taehee Yoo, Vladimir Oltean, Willem de Bruijn, Yadu Kishore,
	linux-kernel, linux-nfs, netdev

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


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 03/27] net: core: fix some kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
  2020-11-16 10:17 ` [PATCH v4 01/27] net: phy: fix " Mauro Carvalho Chehab
  2020-11-16 10:17 ` [PATCH v4 02/27] net: datagram: fix some " Mauro Carvalho Chehab
@ 2020-11-16 10:17 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 04/27] s390: fix " Mauro Carvalho Chehab
                   ` (24 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:17 UTC (permalink / raw)
  To: David S. Miller, Jakub Kicinski
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-kernel, netdev

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


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 04/27] s390: fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (2 preceding siblings ...)
  2020-11-16 10:17 ` [PATCH v4 03/27] net: core: " Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:25   ` Cornelia Huck
  2020-11-16 10:38   ` Vineeth Vijayan
  2020-11-16 10:18 ` [PATCH v4 05/27] drm: fix some " Mauro Carvalho Chehab
                   ` (23 subsequent siblings)
  27 siblings, 2 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Alexander Egorenkov,
	Alexandra Winter, Christian Borntraeger, Heiko Carstens,
	Julian Wiedmann, Peter Oberparleiter, Sven Schnelle,
	Vasily Gorbik, Vineeth Vijayan, linux-kernel, linux-s390

fix one typo:
	ccw driver -> ccw_driver

and one function rename.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 arch/s390/include/asm/ccwdev.h | 2 +-
 arch/s390/include/asm/cio.h    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/arch/s390/include/asm/ccwdev.h b/arch/s390/include/asm/ccwdev.h
index bf605e1fcf6a..0495ac635ed5 100644
--- a/arch/s390/include/asm/ccwdev.h
+++ b/arch/s390/include/asm/ccwdev.h
@@ -100,41 +100,41 @@ struct ccw_device {
  */
 #define PE_NONE				0x0
 #define PE_PATH_GONE			0x1 /* A path is no longer available. */
 #define PE_PATH_AVAILABLE		0x2 /* A path has become available and
 					       was successfully verified. */
 #define PE_PATHGROUP_ESTABLISHED	0x4 /* A pathgroup was reset and had
 					       to be established again. */
 #define PE_PATH_FCES_EVENT		0x8 /* The FCES Status of a path has
 					     * changed. */
 
 /*
  * Possible CIO actions triggered by the unit check handler.
  */
 enum uc_todo {
 	UC_TODO_RETRY,
 	UC_TODO_RETRY_ON_NEW_PATH,
 	UC_TODO_STOP
 };
 
 /**
- * struct ccw driver - device driver for channel attached devices
+ * struct ccw_driver - device driver for channel attached devices
  * @ids: ids supported by this driver
  * @probe: function called on probe
  * @remove: function called on remove
  * @set_online: called when setting device online
  * @set_offline: called when setting device offline
  * @notify: notify driver of device state changes
  * @path_event: notify driver of channel path events
  * @shutdown: called at device shutdown
  * @prepare: prepare for pm state transition
  * @complete: undo work done in @prepare
  * @freeze: callback for freezing during hibernation snapshotting
  * @thaw: undo work done in @freeze
  * @restore: callback for restoring after hibernation
  * @uc_handler: callback for unit check handler
  * @driver: embedded device driver structure
  * @int_class: interruption class to use for accounting interrupts
  */
 struct ccw_driver {
 	struct ccw_device_id *ids;
 	int (*probe) (struct ccw_device *);
diff --git a/arch/s390/include/asm/cio.h b/arch/s390/include/asm/cio.h
index e36cb67d2441..ac02df906cae 100644
--- a/arch/s390/include/asm/cio.h
+++ b/arch/s390/include/asm/cio.h
@@ -312,41 +312,41 @@ struct node_descriptor {
 /* Device did not respond in time. */
 #define CIO_BOXED      0x0010
 
 /**
  * struct ccw_dev_id - unique identifier for ccw devices
  * @ssid: subchannel set id
  * @devno: device number
  *
  * This structure is not directly based on any hardware structure. The
  * hardware identifies a device by its device number and its subchannel,
  * which is in turn identified by its id. In order to get a unique identifier
  * for ccw devices across subchannel sets, @struct ccw_dev_id has been
  * introduced.
  */
 struct ccw_dev_id {
 	u8 ssid;
 	u16 devno;
 };
 
 /**
- * ccw_device_id_is_equal() - compare two ccw_dev_ids
+ * ccw_dev_id_is_equal() - compare two ccw_dev_ids
  * @dev_id1: a ccw_dev_id
  * @dev_id2: another ccw_dev_id
  * Returns:
  *  %1 if the two structures are equal field-by-field,
  *  %0 if not.
  * Context:
  *  any
  */
 static inline int ccw_dev_id_is_equal(struct ccw_dev_id *dev_id1,
 				      struct ccw_dev_id *dev_id2)
 {
 	if ((dev_id1->ssid == dev_id2->ssid) &&
 	    (dev_id1->devno == dev_id2->devno))
 		return 1;
 	return 0;
 }
 
 /**
  * pathmask_to_pos() - find the position of the left-most bit in a pathmask
  * @mask: pathmask with at least one bit set
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 05/27] drm: fix some kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (3 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 04/27] s390: fix " Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 11:37   ` Jani Nikula
  2020-11-16 10:18 ` [PATCH v4 06/27] HSI: fix a kernel-doc markup Mauro Carvalho Chehab
                   ` (22 subsequent siblings)
  27 siblings, 1 reply; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Daniel Vetter, David Airlie, Maarten Lankhorst, Maxime Ripard,
	Thomas Zimmermann
  Cc: Mauro Carvalho Chehab, Christian König, Jonathan Corbet,
	José Roberto de Souza, Linux Doc Mailing List,
	Ville Syrjälä,
	Alex Deucher, Andrey Grodzovsky, Eric Anholt, Imre Deak,
	Jani Nikula, Joonas Lahtinen, Luben Tuikov, Lucas Stach,
	Matt Roper, Nirmoy Das, Pankaj Bharadiya, Rodrigo Vivi,
	Tejas Upadhyay, Wambui Karuga, Yintian Tao, changzhu, dri-devel,
	intel-gfx, linux-kernel

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

Others need to be fixed, as kernel-doc markups should use this format:
        identifier - description

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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 +-
 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 ++++----
 20 files changed, 32 insertions(+), 28 deletions(-)

diff --git a/drivers/gpu/drm/drm_atomic_state_helper.c b/drivers/gpu/drm/drm_atomic_state_helper.c
index 9ad74045158e..ddcf5c2c8e6a 100644
--- a/drivers/gpu/drm/drm_atomic_state_helper.c
+++ b/drivers/gpu/drm/drm_atomic_state_helper.c
@@ -526,41 +526,41 @@ __drm_atomic_helper_connector_destroy_state(struct drm_connector_state *state)
 }
 EXPORT_SYMBOL(__drm_atomic_helper_connector_destroy_state);
 
 /**
  * drm_atomic_helper_connector_destroy_state - default state destroy hook
  * @connector: drm connector
  * @state: connector state object to release
  *
  * Default connector state destroy hook for drivers which don't have their own
  * subclassed connector state structure.
  */
 void drm_atomic_helper_connector_destroy_state(struct drm_connector *connector,
 					  struct drm_connector_state *state)
 {
 	__drm_atomic_helper_connector_destroy_state(state);
 	kfree(state);
 }
 EXPORT_SYMBOL(drm_atomic_helper_connector_destroy_state);
 
 /**
- * __drm_atomic_helper_private_duplicate_state - copy atomic private state
+ * __drm_atomic_helper_private_obj_duplicate_state - copy atomic private state
  * @obj: CRTC object
  * @state: new private object state
  *
  * Copies atomic state from a private objects's current state and resets inferred values.
  * This is useful for drivers that subclass the private state.
  */
 void __drm_atomic_helper_private_obj_duplicate_state(struct drm_private_obj *obj,
 						     struct drm_private_state *state)
 {
 	memcpy(state, obj->state, sizeof(*state));
 }
 EXPORT_SYMBOL(__drm_atomic_helper_private_obj_duplicate_state);
 
 /**
  * __drm_atomic_helper_bridge_duplicate_state() - Copy atomic bridge state
  * @bridge: bridge object
  * @state: atomic bridge state
  *
  * Copies atomic state from a bridge's current state and resets inferred values.
  * This is useful for drivers that subclass the bridge state.
diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
index 1913d8b4e16a..98b6ec45ef96 100644
--- a/drivers/gpu/drm/drm_connector.c
+++ b/drivers/gpu/drm/drm_connector.c
@@ -1415,41 +1415,42 @@ void drm_hdmi_avi_infoframe_content_type(struct hdmi_avi_infoframe *frame,
 		break;
 	case DRM_MODE_CONTENT_TYPE_CINEMA:
 		frame->content_type = HDMI_CONTENT_TYPE_CINEMA;
 		break;
 	case DRM_MODE_CONTENT_TYPE_GAME:
 		frame->content_type = HDMI_CONTENT_TYPE_GAME;
 		break;
 	case DRM_MODE_CONTENT_TYPE_PHOTO:
 		frame->content_type = HDMI_CONTENT_TYPE_PHOTO;
 		break;
 	default:
 		/* Graphics is the default(0) */
 		frame->content_type = HDMI_CONTENT_TYPE_GRAPHICS;
 	}
 
 	frame->itc = conn_state->content_type != DRM_MODE_CONTENT_TYPE_NO_DATA;
 }
 EXPORT_SYMBOL(drm_hdmi_avi_infoframe_content_type);
 
 /**
- * drm_mode_attach_tv_margin_properties - attach TV connector margin properties
+ * drm_connector_attach_tv_margin_properties - attach TV connector margin
+ * 	properties
  * @connector: DRM connector
  *
  * Called by a driver when it needs to attach TV margin props to a connector.
  * Typically used on SDTV and HDMI connectors.
  */
 void drm_connector_attach_tv_margin_properties(struct drm_connector *connector)
 {
 	struct drm_device *dev = connector->dev;
 
 	drm_object_attach_property(&connector->base,
 				   dev->mode_config.tv_left_margin_property,
 				   0);
 	drm_object_attach_property(&connector->base,
 				   dev->mode_config.tv_right_margin_property,
 				   0);
 	drm_object_attach_property(&connector->base,
 				   dev->mode_config.tv_top_margin_property,
 				   0);
 	drm_object_attach_property(&connector->base,
 				   dev->mode_config.tv_bottom_margin_property,
diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
index 37ec3b94389c..5bd0934004e3 100644
--- a/drivers/gpu/drm/drm_dp_helper.c
+++ b/drivers/gpu/drm/drm_dp_helper.c
@@ -1144,41 +1144,41 @@ drm_dp_subconnector_type(const u8 dpcd[DP_RECEIVER_CAP_SIZE],
 	switch (type) {
 	case DP_DS_PORT_TYPE_DP:
 	case DP_DS_PORT_TYPE_DP_DUALMODE:
 		return DRM_MODE_SUBCONNECTOR_DisplayPort;
 	case DP_DS_PORT_TYPE_VGA:
 		return DRM_MODE_SUBCONNECTOR_VGA;
 	case DP_DS_PORT_TYPE_DVI:
 		return DRM_MODE_SUBCONNECTOR_DVID;
 	case DP_DS_PORT_TYPE_HDMI:
 		return DRM_MODE_SUBCONNECTOR_HDMIA;
 	case DP_DS_PORT_TYPE_WIRELESS:
 		return DRM_MODE_SUBCONNECTOR_Wireless;
 	case DP_DS_PORT_TYPE_NON_EDID:
 	default:
 		return DRM_MODE_SUBCONNECTOR_Unknown;
 	}
 }
 EXPORT_SYMBOL(drm_dp_subconnector_type);
 
 /**
- * drm_mode_set_dp_subconnector_property - set subconnector for DP connector
+ * drm_dp_set_subconnector_property - set subconnector for DP connector
  * @connector: connector to set property on
  * @status: connector status
  * @dpcd: DisplayPort configuration data
  * @port_cap: port capabilities
  *
  * Called by a driver on every detect event.
  */
 void drm_dp_set_subconnector_property(struct drm_connector *connector,
 				      enum drm_connector_status status,
 				      const u8 *dpcd,
 				      const u8 port_cap[4])
 {
 	enum drm_mode_subconnector subconnector = DRM_MODE_SUBCONNECTOR_Unknown;
 
 	if (status == connector_status_connected)
 		subconnector = drm_dp_subconnector_type(dpcd, port_cap);
 	drm_object_property_set_value(&connector->base,
 			connector->dev->mode_config.dp_subconnector_property,
 			subconnector);
 }
diff --git a/drivers/gpu/drm/drm_framebuffer.c b/drivers/gpu/drm/drm_framebuffer.c
index 2f5b0c2bb0fe..aca62ed51e82 100644
--- a/drivers/gpu/drm/drm_framebuffer.c
+++ b/drivers/gpu/drm/drm_framebuffer.c
@@ -535,41 +535,41 @@ int drm_mode_getfb(struct drm_device *dev,
 
 	/* GET_FB() is an unprivileged ioctl so we must not return a
 	 * buffer-handle to non-master processes! For
 	 * backwards-compatibility reasons, we cannot make GET_FB() privileged,
 	 * so just return an invalid handle for non-masters.
 	 */
 	if (!drm_is_current_master(file_priv) && !capable(CAP_SYS_ADMIN)) {
 		r->handle = 0;
 		ret = 0;
 		goto out;
 	}
 
 	ret = fb->funcs->create_handle(fb, file_priv, &r->handle);
 
 out:
 	drm_framebuffer_put(fb);
 	return ret;
 }
 
 /**
- * drm_mode_getfb2 - get extended FB info
+ * drm_mode_getfb2_ioctl - get extended FB info
  * @dev: drm device for the ioctl
  * @data: data pointer for the ioctl
  * @file_priv: drm file for the ioctl call
  *
  * Lookup the FB given its ID and return info about it.
  *
  * Called by the user via ioctl.
  *
  * Returns:
  * Zero on success, negative errno on failure.
  */
 int drm_mode_getfb2_ioctl(struct drm_device *dev,
 			  void *data, struct drm_file *file_priv)
 {
 	struct drm_mode_fb_cmd2 *r = data;
 	struct drm_framebuffer *fb;
 	unsigned int i;
 	int ret;
 
 	if (!drm_core_check_feature(dev, DRIVER_MODESET))
diff --git a/drivers/gpu/drm/drm_gem.c b/drivers/gpu/drm/drm_gem.c
index eb2d23e04be9..92f89cee213e 100644
--- a/drivers/gpu/drm/drm_gem.c
+++ b/drivers/gpu/drm/drm_gem.c
@@ -850,41 +850,41 @@ drm_gem_flink_ioctl(struct drm_device *dev, void *data,
 	}
 
 	if (!obj->name) {
 		ret = idr_alloc(&dev->object_name_idr, obj, 1, 0, GFP_KERNEL);
 		if (ret < 0)
 			goto err;
 
 		obj->name = ret;
 	}
 
 	args->name = (uint64_t) obj->name;
 	ret = 0;
 
 err:
 	mutex_unlock(&dev->object_name_lock);
 	drm_gem_object_put(obj);
 	return ret;
 }
 
 /**
- * drm_gem_open - implementation of the GEM_OPEN ioctl
+ * drm_gem_open_ioctl - implementation of the GEM_OPEN ioctl
  * @dev: drm_device
  * @data: ioctl data
  * @file_priv: drm file-private structure
  *
  * Open an object using the global name, returning a handle and the size.
  *
  * This handle (of course) holds a reference to the object, so the object
  * will not go away until the handle is deleted.
  */
 int
 drm_gem_open_ioctl(struct drm_device *dev, void *data,
 		   struct drm_file *file_priv)
 {
 	struct drm_gem_open *args = data;
 	struct drm_gem_object *obj;
 	int ret;
 	u32 handle;
 
 	if (!drm_core_check_feature(dev, DRIVER_GEM))
 		return -EOPNOTSUPP;
@@ -895,41 +895,41 @@ drm_gem_open_ioctl(struct drm_device *dev, void *data,
 		drm_gem_object_get(obj);
 	} else {
 		mutex_unlock(&dev->object_name_lock);
 		return -ENOENT;
 	}
 
 	/* drm_gem_handle_create_tail unlocks dev->object_name_lock. */
 	ret = drm_gem_handle_create_tail(file_priv, obj, &handle);
 	if (ret)
 		goto err;
 
 	args->handle = handle;
 	args->size = obj->size;
 
 err:
 	drm_gem_object_put(obj);
 	return ret;
 }
 
 /**
- * gem_gem_open - initalizes GEM file-private structures at devnode open time
+ * drm_gem_open - initalizes GEM file-private structures at devnode open time
  * @dev: drm_device which is being opened by userspace
  * @file_private: drm file-private structure to set up
  *
  * Called at device open time, sets up the structure for handling refcounting
  * of mm objects.
  */
 void
 drm_gem_open(struct drm_device *dev, struct drm_file *file_private)
 {
 	idr_init_base(&file_private->object_idr, 1);
 	spin_lock_init(&file_private->table_lock);
 }
 
 /**
  * drm_gem_release - release file-private GEM resources
  * @dev: drm_device which is being closed by userspace
  * @file_private: drm file-private structure to clean up
  *
  * Called at close time when the filp is going away.
  *
diff --git a/drivers/gpu/drm/drm_gem_vram_helper.c b/drivers/gpu/drm/drm_gem_vram_helper.c
index 889a06696f7e..02ca22e90290 100644
--- a/drivers/gpu/drm/drm_gem_vram_helper.c
+++ b/drivers/gpu/drm/drm_gem_vram_helper.c
@@ -600,41 +600,41 @@ static int drm_gem_vram_bo_driver_move(struct drm_gem_vram_object *gbo,
  * Helpers for struct drm_gem_object_funcs
  */
 
 /**
  * drm_gem_vram_object_free() - \
 	Implements &struct drm_gem_object_funcs.free
  * @gem:       GEM object. Refers to &struct drm_gem_vram_object.gem
  */
 static void drm_gem_vram_object_free(struct drm_gem_object *gem)
 {
 	struct drm_gem_vram_object *gbo = drm_gem_vram_of_gem(gem);
 
 	drm_gem_vram_put(gbo);
 }
 
 /*
  * Helpers for dump buffers
  */
 
 /**
- * drm_gem_vram_driver_create_dumb() - \
+ * drm_gem_vram_driver_dumb_create() - \
 	Implements &struct drm_driver.dumb_create
  * @file:		the DRM file
  * @dev:		the DRM device
  * @args:		the arguments as provided to \
 				&struct drm_driver.dumb_create
  *
  * This function requires the driver to use @drm_device.vram_mm for its
  * instance of VRAM MM.
  *
  * Returns:
  * 0 on success, or
  * a negative error code otherwise.
  */
 int drm_gem_vram_driver_dumb_create(struct drm_file *file,
 				    struct drm_device *dev,
 				    struct drm_mode_create_dumb *args)
 {
 	if (WARN_ONCE(!dev->vram_mm, "VRAM MM not initialized"))
 		return -EINVAL;
 
diff --git a/drivers/gpu/drm/drm_mode_object.c b/drivers/gpu/drm/drm_mode_object.c
index db05f386a709..b26588b52795 100644
--- a/drivers/gpu/drm/drm_mode_object.c
+++ b/drivers/gpu/drm/drm_mode_object.c
@@ -98,41 +98,41 @@ void drm_mode_object_register(struct drm_device *dev,
  * Free @id from @dev's unique identifier pool.
  * This function can be called multiple times, and guards against
  * multiple removals.
  * These modeset identifiers are _not_ reference counted. Hence don't use this
  * for reference counted modeset objects like framebuffers.
  */
 void drm_mode_object_unregister(struct drm_device *dev,
 				struct drm_mode_object *object)
 {
 	WARN_ON(!dev->driver->load && dev->registered && !object->free_cb);
 
 	mutex_lock(&dev->mode_config.idr_mutex);
 	if (object->id) {
 		idr_remove(&dev->mode_config.object_idr, object->id);
 		object->id = 0;
 	}
 	mutex_unlock(&dev->mode_config.idr_mutex);
 }
 
 /**
- * drm_lease_required - check types which must be leased to be used
+ * drm_mode_object_lease_required - check types which must be leased to be used
  * @type: type of object
  *
  * Returns whether the provided type of drm_mode_object must
  * be owned or leased to be used by a process.
  */
 bool drm_mode_object_lease_required(uint32_t type)
 {
 	switch(type) {
 	case DRM_MODE_OBJECT_CRTC:
 	case DRM_MODE_OBJECT_CONNECTOR:
 	case DRM_MODE_OBJECT_PLANE:
 		return true;
 	default:
 		return false;
 	}
 }
 
 struct drm_mode_object *__drm_mode_object_find(struct drm_device *dev,
 					       struct drm_file *file_priv,
 					       uint32_t id, uint32_t type)
diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c
index 501b4fe55a3d..33fb2f05ce66 100644
--- a/drivers/gpu/drm/drm_modes.c
+++ b/drivers/gpu/drm/drm_modes.c
@@ -1872,41 +1872,41 @@ drm_mode_create_from_cmdline_mode(struct drm_device *dev,
 				    cmd->margins);
 	else
 		mode = drm_gtf_mode(dev,
 				    cmd->xres, cmd->yres,
 				    cmd->refresh_specified ? cmd->refresh : 60,
 				    cmd->interlace,
 				    cmd->margins);
 	if (!mode)
 		return NULL;
 
 	mode->type |= DRM_MODE_TYPE_USERDEF;
 	/* fix up 1368x768: GFT/CVT can't express 1366 width due to alignment */
 	if (cmd->xres == 1366)
 		drm_mode_fixup_1366x768(mode);
 	drm_mode_set_crtcinfo(mode, CRTC_INTERLACE_HALVE_V);
 	return mode;
 }
 EXPORT_SYMBOL(drm_mode_create_from_cmdline_mode);
 
 /**
- * drm_crtc_convert_to_umode - convert a drm_display_mode into a modeinfo
+ * drm_mode_convert_to_umode - convert a drm_display_mode into a modeinfo
  * @out: drm_mode_modeinfo struct to return to the user
  * @in: drm_display_mode to use
  *
  * Convert a drm_display_mode into a drm_mode_modeinfo structure to return to
  * the user.
  */
 void drm_mode_convert_to_umode(struct drm_mode_modeinfo *out,
 			       const struct drm_display_mode *in)
 {
 	out->clock = in->clock;
 	out->hdisplay = in->hdisplay;
 	out->hsync_start = in->hsync_start;
 	out->hsync_end = in->hsync_end;
 	out->htotal = in->htotal;
 	out->hskew = in->hskew;
 	out->vdisplay = in->vdisplay;
 	out->vsync_start = in->vsync_start;
 	out->vsync_end = in->vsync_end;
 	out->vtotal = in->vtotal;
 	out->vscan = in->vscan;
@@ -1924,41 +1924,41 @@ void drm_mode_convert_to_umode(struct drm_mode_modeinfo *out,
 	case HDMI_PICTURE_ASPECT_64_27:
 		out->flags |= DRM_MODE_FLAG_PIC_AR_64_27;
 		break;
 	case HDMI_PICTURE_ASPECT_256_135:
 		out->flags |= DRM_MODE_FLAG_PIC_AR_256_135;
 		break;
 	default:
 		WARN(1, "Invalid aspect ratio (0%x) on mode\n",
 		     in->picture_aspect_ratio);
 		fallthrough;
 	case HDMI_PICTURE_ASPECT_NONE:
 		out->flags |= DRM_MODE_FLAG_PIC_AR_NONE;
 		break;
 	}
 
 	strncpy(out->name, in->name, DRM_DISPLAY_MODE_LEN);
 	out->name[DRM_DISPLAY_MODE_LEN-1] = 0;
 }
 
 /**
- * drm_crtc_convert_umode - convert a modeinfo into a drm_display_mode
+ * drm_mode_convert_umode - convert a modeinfo into a drm_display_mode
  * @dev: drm device
  * @out: drm_display_mode to return to the user
  * @in: drm_mode_modeinfo to use
  *
  * Convert a drm_mode_modeinfo into a drm_display_mode structure to return to
  * the caller.
  *
  * Returns:
  * Zero on success, negative errno on failure.
  */
 int drm_mode_convert_umode(struct drm_device *dev,
 			   struct drm_display_mode *out,
 			   const struct drm_mode_modeinfo *in)
 {
 	if (in->clock > INT_MAX || in->vrefresh > INT_MAX)
 		return -ERANGE;
 
 	out->clock = in->clock;
 	out->hdisplay = in->hdisplay;
 	out->hsync_start = in->hsync_start;
diff --git a/drivers/gpu/drm/drm_scdc_helper.c b/drivers/gpu/drm/drm_scdc_helper.c
index 311e71bbba5b..991b8c86d78d 100644
--- a/drivers/gpu/drm/drm_scdc_helper.c
+++ b/drivers/gpu/drm/drm_scdc_helper.c
@@ -108,41 +108,41 @@ ssize_t drm_scdc_write(struct i2c_adapter *adapter, u8 offset,
 
 	msg.buf = data;
 
 	memcpy(data, &offset, sizeof(offset));
 	memcpy(data + 1, buffer, size);
 
 	err = i2c_transfer(adapter, &msg, 1);
 
 	kfree(data);
 
 	if (err < 0)
 		return err;
 	if (err != 1)
 		return -EPROTO;
 
 	return 0;
 }
 EXPORT_SYMBOL(drm_scdc_write);
 
 /**
- * drm_scdc_check_scrambling_status - what is status of scrambling?
+ * drm_scdc_get_scrambling_status - what is status of scrambling?
  * @adapter: I2C adapter for DDC channel
  *
  * Reads the scrambler status over SCDC, and checks the
  * scrambling status.
  *
  * Returns:
  * True if the scrambling is enabled, false otherwise.
  */
 bool drm_scdc_get_scrambling_status(struct i2c_adapter *adapter)
 {
 	u8 status;
 	int ret;
 
 	ret = drm_scdc_readb(adapter, SCDC_SCRAMBLER_STATUS, &status);
 	if (ret < 0) {
 		DRM_DEBUG_KMS("Failed to read scrambling status: %d\n", ret);
 		return false;
 	}
 
 	return status & SCDC_SCRAMBLING_STATUS;
diff --git a/drivers/gpu/drm/i915/display/intel_dpll_mgr.c b/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
index a95e6a2ac698..8753bab20ce8 100644
--- a/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
+++ b/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
@@ -4573,41 +4573,41 @@ static void sanitize_dpll_state(struct drm_i915_private *i915,
 	if (!pll->on || pll->active_mask)
 		return;
 
 	drm_dbg_kms(&i915->drm,
 		    "%s enabled but not in use, disabling\n",
 		    pll->info->name);
 
 	pll->info->funcs->disable(i915, pll);
 	pll->on = false;
 }
 
 void intel_dpll_sanitize_state(struct drm_i915_private *i915)
 {
 	int i;
 
 	for (i = 0; i < i915->dpll.num_shared_dpll; i++)
 		sanitize_dpll_state(i915, &i915->dpll.shared_dplls[i]);
 }
 
 /**
- * intel_shared_dpll_dump_hw_state - write hw_state to dmesg
+ * intel_dpll_dump_hw_state - write hw_state to dmesg
  * @dev_priv: i915 drm device
  * @hw_state: hw state to be written to the log
  *
  * Write the relevant values in @hw_state to dmesg using drm_dbg_kms.
  */
 void intel_dpll_dump_hw_state(struct drm_i915_private *dev_priv,
 			      const struct intel_dpll_hw_state *hw_state)
 {
 	if (dev_priv->dpll.mgr) {
 		dev_priv->dpll.mgr->dump_hw_state(dev_priv, hw_state);
 	} else {
 		/* fallback for platforms that don't use the shared dpll
 		 * infrastructure
 		 */
 		drm_dbg_kms(&dev_priv->drm,
 			    "dpll_hw_state: dpll: 0x%x, dpll_md: 0x%x, "
 			    "fp0: 0x%x, fp1: 0x%x\n",
 			    hw_state->dpll,
 			    hw_state->dpll_md,
 			    hw_state->fp0,
diff --git a/drivers/gpu/drm/i915/i915_gem_evict.c b/drivers/gpu/drm/i915/i915_gem_evict.c
index 6501939929d5..e1a66c8245b8 100644
--- a/drivers/gpu/drm/i915/i915_gem_evict.c
+++ b/drivers/gpu/drm/i915/i915_gem_evict.c
@@ -221,41 +221,41 @@ i915_gem_evict_something(struct i915_address_space *vm,
 	list_for_each_entry_safe(vma, next, &eviction_list, evict_link) {
 		__i915_vma_unpin(vma);
 		if (ret == 0)
 			ret = __i915_vma_unbind(vma);
 	}
 
 	while (ret == 0 && (node = drm_mm_scan_color_evict(&scan))) {
 		vma = container_of(node, struct i915_vma, node);
 
 		/* If we find any non-objects (!vma), we cannot evict them */
 		if (vma->node.color != I915_COLOR_UNEVICTABLE)
 			ret = __i915_vma_unbind(vma);
 		else
 			ret = -ENOSPC; /* XXX search failed, try again? */
 	}
 
 	return ret;
 }
 
 /**
- * i915_gem_evict_for_vma - Evict vmas to make room for binding a new one
+ * i915_gem_evict_for_node - Evict vmas to make room for binding a new one
  * @vm: address space to evict from
  * @target: range (and color) to evict for
  * @flags: additional flags to control the eviction algorithm
  *
  * This function will try to evict vmas that overlap the target node.
  *
  * To clarify: This is for freeing up virtual address space, not for freeing
  * memory in e.g. the shrinker.
  */
 int i915_gem_evict_for_node(struct i915_address_space *vm,
 			    struct drm_mm_node *target,
 			    unsigned int flags)
 {
 	LIST_HEAD(eviction_list);
 	struct drm_mm_node *node;
 	u64 start = target->start;
 	u64 end = start + target->size;
 	struct i915_vma *vma, *next;
 	int ret = 0;
 
diff --git a/drivers/gpu/drm/i915/i915_perf.c b/drivers/gpu/drm/i915/i915_perf.c
index e94976976571..3ced82820483 100644
--- a/drivers/gpu/drm/i915/i915_perf.c
+++ b/drivers/gpu/drm/i915/i915_perf.c
@@ -608,41 +608,42 @@ static int append_oa_sample(struct i915_perf_stream *stream,
 
 	if ((count - *offset) < header.size)
 		return -ENOSPC;
 
 	buf += *offset;
 	if (copy_to_user(buf, &header, sizeof(header)))
 		return -EFAULT;
 	buf += sizeof(header);
 
 	if (sample_flags & SAMPLE_OA_REPORT) {
 		if (copy_to_user(buf, report, report_size))
 			return -EFAULT;
 	}
 
 	(*offset) += header.size;
 
 	return 0;
 }
 
 /**
- * Copies all buffered OA reports into userspace read() buffer.
+ * gen8_append_oa_reports - Copies all buffered OA reports into
+ *			    userspace read() buffer.
  * @stream: An i915-perf stream opened for OA metrics
  * @buf: destination buffer given by userspace
  * @count: the number of bytes userspace wants to read
  * @offset: (inout): the current position for writing into @buf
  *
  * Notably any error condition resulting in a short read (-%ENOSPC or
  * -%EFAULT) will be returned even though one or more records may
  * have been successfully copied. In this case it's up to the caller
  * to decide if the error should be squashed before returning to
  * userspace.
  *
  * Note: reports are consumed from the head, and appended to the
  * tail, so the tail chases the head?... If you think that's mad
  * and back-to-front you're not alone, but this follows the
  * Gen PRM naming convention.
  *
  * Returns: 0 on success, negative error code on failure.
  */
 static int gen8_append_oa_reports(struct i915_perf_stream *stream,
 				  char __user *buf,
@@ -900,41 +901,42 @@ static int gen8_oa_read(struct i915_perf_stream *stream,
 		/*
 		 * Note: .oa_enable() is expected to re-init the oabuffer and
 		 * reset GEN8_OASTATUS for us
 		 */
 		oastatus = intel_uncore_read(uncore, oastatus_reg);
 	}
 
 	if (oastatus & GEN8_OASTATUS_REPORT_LOST) {
 		ret = append_oa_status(stream, buf, count, offset,
 				       DRM_I915_PERF_RECORD_OA_REPORT_LOST);
 		if (ret)
 			return ret;
 		intel_uncore_write(uncore, oastatus_reg,
 				   oastatus & ~GEN8_OASTATUS_REPORT_LOST);
 	}
 
 	return gen8_append_oa_reports(stream, buf, count, offset);
 }
 
 /**
- * Copies all buffered OA reports into userspace read() buffer.
+ * gen7_append_oa_reports - Copies all buffered OA reports into
+ *			    userspace read() buffer.
  * @stream: An i915-perf stream opened for OA metrics
  * @buf: destination buffer given by userspace
  * @count: the number of bytes userspace wants to read
  * @offset: (inout): the current position for writing into @buf
  *
  * Notably any error condition resulting in a short read (-%ENOSPC or
  * -%EFAULT) will be returned even though one or more records may
  * have been successfully copied. In this case it's up to the caller
  * to decide if the error should be squashed before returning to
  * userspace.
  *
  * Note: reports are consumed from the head, and appended to the
  * tail, so the tail chases the head?... If you think that's mad
  * and back-to-front you're not alone, but this follows the
  * Gen PRM naming convention.
  *
  * Returns: 0 on success, negative error code on failure.
  */
 static int gen7_append_oa_reports(struct i915_perf_stream *stream,
 				  char __user *buf,
@@ -3210,41 +3212,41 @@ static long i915_perf_config_locked(struct i915_perf_stream *stream,
 		 * reconfiguration inline from that context. The update
 		 * will then be ordered with respect to submission on that
 		 * context.
 		 *
 		 * When set globally, we use a low priority kernel context,
 		 * so it will effectively take effect when idle.
 		 */
 		err = emit_oa_config(stream, config, oa_context(stream), NULL);
 		if (!err)
 			config = xchg(&stream->oa_config, config);
 		else
 			ret = err;
 	}
 
 	i915_oa_config_put(config);
 
 	return ret;
 }
 
 /**
- * i915_perf_ioctl - support ioctl() usage with i915 perf stream FDs
+ * i915_perf_ioctl_locked - support ioctl() usage with i915 perf stream FDs
  * @stream: An i915 perf stream
  * @cmd: the ioctl request
  * @arg: the ioctl data
  *
  * Note: The &perf->lock mutex has been taken to serialize
  * with any non-file-operation driver hooks.
  *
  * Returns: zero on success or a negative error code. Returns -EINVAL for
  * an unknown ioctl request.
  */
 static long i915_perf_ioctl_locked(struct i915_perf_stream *stream,
 				   unsigned int cmd,
 				   unsigned long arg)
 {
 	switch (cmd) {
 	case I915_PERF_IOCTL_ENABLE:
 		i915_perf_enable_locked(stream);
 		return 0;
 	case I915_PERF_IOCTL_DISABLE:
 		i915_perf_disable_locked(stream);
diff --git a/drivers/gpu/drm/scheduler/sched_main.c b/drivers/gpu/drm/scheduler/sched_main.c
index da24c4e8b9fb..b498d474ef9e 100644
--- a/drivers/gpu/drm/scheduler/sched_main.c
+++ b/drivers/gpu/drm/scheduler/sched_main.c
@@ -430,41 +430,41 @@ void drm_sched_stop(struct drm_gpu_scheduler *sched, struct drm_sched_job *bad)
 			 */
 			if (bad != s_job)
 				sched->ops->free_job(s_job);
 			else
 				sched->free_guilty = true;
 		}
 	}
 
 	/*
 	 * Stop pending timer in flight as we rearm it in  drm_sched_start. This
 	 * avoids the pending timeout work in progress to fire right away after
 	 * this TDR finished and before the newly restarted jobs had a
 	 * chance to complete.
 	 */
 	cancel_delayed_work(&sched->work_tdr);
 }
 
 EXPORT_SYMBOL(drm_sched_stop);
 
 /**
- * drm_sched_job_recovery - recover jobs after a reset
+ * drm_sched_start - recover jobs after a reset
  *
  * @sched: scheduler instance
  * @full_recovery: proceed with complete sched restart
  *
  */
 void drm_sched_start(struct drm_gpu_scheduler *sched, bool full_recovery)
 {
 	struct drm_sched_job *s_job, *tmp;
 	int r;
 
 	/*
 	 * Locking the list is not required here as the sched thread is parked
 	 * so no new jobs are being inserted or removed. Also concurrent
 	 * GPU recovers can't run in parallel.
 	 */
 	list_for_each_entry_safe(s_job, tmp, &sched->ring_mirror_list, node) {
 		struct dma_fence *fence = s_job->s_fence->parent;
 
 		atomic_inc(&sched->hw_rq_count);
 
diff --git a/drivers/gpu/drm/v3d/v3d_sched.c b/drivers/gpu/drm/v3d/v3d_sched.c
index 0747614a78f0..f968f389633a 100644
--- a/drivers/gpu/drm/v3d/v3d_sched.c
+++ b/drivers/gpu/drm/v3d/v3d_sched.c
@@ -47,41 +47,41 @@ to_tfu_job(struct drm_sched_job *sched_job)
 {
 	return container_of(sched_job, struct v3d_tfu_job, base.base);
 }
 
 static struct v3d_csd_job *
 to_csd_job(struct drm_sched_job *sched_job)
 {
 	return container_of(sched_job, struct v3d_csd_job, base.base);
 }
 
 static void
 v3d_job_free(struct drm_sched_job *sched_job)
 {
 	struct v3d_job *job = to_v3d_job(sched_job);
 
 	drm_sched_job_cleanup(sched_job);
 	v3d_job_put(job);
 }
 
 /**
- * Returns the fences that the job depends on, one by one.
+ * v3d_job_dependency - Returns the fences that the job depends on, one by one.
  *
  * If placed in the scheduler's .dependency method, the corresponding
  * .run_job won't be called until all of them have been signaled.
  */
 static struct dma_fence *
 v3d_job_dependency(struct drm_sched_job *sched_job,
 		   struct drm_sched_entity *s_entity)
 {
 	struct v3d_job *job = to_v3d_job(sched_job);
 
 	/* XXX: Wait on a fence for switching the GMP if necessary,
 	 * and then do so.
 	 */
 
 	if (!xa_empty(&job->deps))
 		return xa_erase(&job->deps, job->last_dep++);
 
 	return NULL;
 }
 
diff --git a/drivers/gpu/drm/vc4/vc4_bo.c b/drivers/gpu/drm/vc4/vc4_bo.c
index a21a6c53ffcf..469d1b4f2643 100644
--- a/drivers/gpu/drm/vc4/vc4_bo.c
+++ b/drivers/gpu/drm/vc4/vc4_bo.c
@@ -374,41 +374,41 @@ static struct vc4_bo *vc4_bo_get_from_cache(struct drm_device *dev,
 		vc4_bo_set_label(&bo->base.base, type);
 	mutex_unlock(&vc4->bo_lock);
 	return bo;
 }
 
 static const struct vm_operations_struct vc4_vm_ops = {
 	.fault = vc4_fault,
 	.open = drm_gem_vm_open,
 	.close = drm_gem_vm_close,
 };
 
 static const struct drm_gem_object_funcs vc4_gem_object_funcs = {
 	.free = vc4_free_object,
 	.export = vc4_prime_export,
 	.get_sg_table = drm_gem_cma_prime_get_sg_table,
 	.vmap = vc4_prime_vmap,
 	.vm_ops = &vc4_vm_ops,
 };
 
 /**
- * vc4_gem_create_object - Implementation of driver->gem_create_object.
+ * vc4_create_object - Implementation of driver->gem_create_object.
  * @dev: DRM device
  * @size: Size in bytes of the memory the object will reference
  *
  * This lets the CMA helpers allocate object structs for us, and keep
  * our BO stats correct.
  */
 struct drm_gem_object *vc4_create_object(struct drm_device *dev, size_t size)
 {
 	struct vc4_dev *vc4 = to_vc4_dev(dev);
 	struct vc4_bo *bo;
 
 	bo = kzalloc(sizeof(*bo), GFP_KERNEL);
 	if (!bo)
 		return ERR_PTR(-ENOMEM);
 
 	bo->madv = VC4_MADV_WILLNEED;
 	refcount_set(&bo->usecnt, 0);
 	mutex_init(&bo->madv_lock);
 	mutex_lock(&vc4->bo_lock);
 	bo->label = VC4_BO_TYPE_KERNEL;
diff --git a/include/drm/drm_atomic_helper.h b/include/drm/drm_atomic_helper.h
index 85df04c8e62f..5f47720440fa 100644
--- a/include/drm/drm_atomic_helper.h
+++ b/include/drm/drm_atomic_helper.h
@@ -150,54 +150,54 @@ int drm_atomic_helper_page_flip_target(
 int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc,
 				       u16 *red, u16 *green, u16 *blue,
 				       uint32_t size,
 				       struct drm_modeset_acquire_ctx *ctx);
 
 /**
  * drm_atomic_crtc_for_each_plane - iterate over planes currently attached to CRTC
  * @plane: the loop cursor
  * @crtc:  the CRTC whose planes are iterated
  *
  * This iterates over the current state, useful (for example) when applying
  * atomic state after it has been checked and swapped.  To iterate over the
  * planes which *will* be attached (more useful in code called from
  * &drm_mode_config_funcs.atomic_check) see
  * drm_atomic_crtc_state_for_each_plane().
  */
 #define drm_atomic_crtc_for_each_plane(plane, crtc) \
 	drm_for_each_plane_mask(plane, (crtc)->dev, (crtc)->state->plane_mask)
 
 /**
- * drm_crtc_atomic_state_for_each_plane - iterate over attached planes in new state
+ * drm_atomic_crtc_state_for_each_plane - iterate over attached planes in new state
  * @plane: the loop cursor
  * @crtc_state: the incoming CRTC state
  *
  * Similar to drm_crtc_for_each_plane(), but iterates the planes that will be
  * attached if the specified state is applied.  Useful during for example
  * in code called from &drm_mode_config_funcs.atomic_check operations, to
  * validate the incoming state.
  */
 #define drm_atomic_crtc_state_for_each_plane(plane, crtc_state) \
 	drm_for_each_plane_mask(plane, (crtc_state)->state->dev, (crtc_state)->plane_mask)
 
 /**
- * drm_crtc_atomic_state_for_each_plane_state - iterate over attached planes in new state
+ * drm_atomic_crtc_state_for_each_plane_state - iterate over attached planes in new state
  * @plane: the loop cursor
  * @plane_state: loop cursor for the plane's state, must be const
  * @crtc_state: the incoming CRTC state
  *
  * Similar to drm_crtc_for_each_plane(), but iterates the planes that will be
  * attached if the specified state is applied.  Useful during for example
  * in code called from &drm_mode_config_funcs.atomic_check operations, to
  * validate the incoming state.
  *
  * Compared to just drm_atomic_crtc_state_for_each_plane() this also fills in a
  * const plane_state. This is useful when a driver just wants to peek at other
  * active planes on this CRTC, but does not need to change it.
  */
 #define drm_atomic_crtc_state_for_each_plane_state(plane, plane_state, crtc_state) \
 	drm_for_each_plane_mask(plane, (crtc_state)->state->dev, (crtc_state)->plane_mask) \
 		for_each_if ((plane_state = \
 			      __drm_atomic_get_current_plane_state((crtc_state)->state, \
 								   plane)))
 
 /**
diff --git a/include/drm/drm_connector.h b/include/drm/drm_connector.h
index 928136556174..fcdc58d8b88b 100644
--- a/include/drm/drm_connector.h
+++ b/include/drm/drm_connector.h
@@ -67,41 +67,41 @@ enum drm_connector_status {
 	 * sink device which can be autodetect. For digital outputs like DP or
 	 * HDMI (which can be realiable probed) this means there's really
 	 * nothing there. It is driver-dependent whether a connector with this
 	 * status can be lit up or not.
 	 */
 	connector_status_disconnected = 2,
 	/**
 	 * @connector_status_unknown: The connector's status could not be
 	 * reliably detected. This happens when probing would either cause
 	 * flicker (like load-detection when the connector is in use), or when a
 	 * hardware resource isn't available (like when load-detection needs a
 	 * free CRTC). It should be possible to light up the connector with one
 	 * of the listed fallback modes. For default configuration userspace
 	 * should only try to light up connectors with unknown status when
 	 * there's not connector with @connector_status_connected.
 	 */
 	connector_status_unknown = 3,
 };
 
 /**
- * enum drm_connector_registration_status - userspace registration status for
+ * enum drm_connector_registration_state - userspace registration status for
  * a &drm_connector
  *
  * This enum is used to track the status of initializing a connector and
  * registering it with userspace, so that DRM can prevent bogus modesets on
  * connectors that no longer exist.
  */
 enum drm_connector_registration_state {
 	/**
 	 * @DRM_CONNECTOR_INITIALIZING: The connector has just been created,
 	 * but has yet to be exposed to userspace. There should be no
 	 * additional restrictions to how the state of this connector may be
 	 * modified.
 	 */
 	DRM_CONNECTOR_INITIALIZING = 0,
 
 	/**
 	 * @DRM_CONNECTOR_REGISTERED: The connector has been fully initialized
 	 * and registered with sysfs, as such it has been exposed to
 	 * userspace. There should be no additional restrictions to how the
 	 * state of this connector may be modified.
diff --git a/include/drm/drm_device.h b/include/drm/drm_device.h
index 2c361964aee7..283a93ce4617 100644
--- a/include/drm/drm_device.h
+++ b/include/drm/drm_device.h
@@ -10,41 +10,41 @@
 #include <drm/drm_mode_config.h>
 
 struct drm_driver;
 struct drm_minor;
 struct drm_master;
 struct drm_device_dma;
 struct drm_vblank_crtc;
 struct drm_sg_mem;
 struct drm_local_map;
 struct drm_vma_offset_manager;
 struct drm_vram_mm;
 struct drm_fb_helper;
 
 struct inode;
 
 struct pci_dev;
 struct pci_controller;
 
 
 /**
- * enum drm_switch_power - power state of drm device
+ * enum switch_power_state - power state of drm device
  */
 
 enum switch_power_state {
 	/** @DRM_SWITCH_POWER_ON: Power state is ON */
 	DRM_SWITCH_POWER_ON = 0,
 
 	/** @DRM_SWITCH_POWER_OFF: Power state is OFF */
 	DRM_SWITCH_POWER_OFF = 1,
 
 	/** @DRM_SWITCH_POWER_CHANGING: Power state is changing */
 	DRM_SWITCH_POWER_CHANGING = 2,
 
 	/** @DRM_SWITCH_POWER_DYNAMIC_OFF: Suspended */
 	DRM_SWITCH_POWER_DYNAMIC_OFF = 3,
 };
 
 /**
  * struct drm_device - DRM device structure
  *
  * This structure represent a complete card that
diff --git a/include/drm/drm_dsc.h b/include/drm/drm_dsc.h
index 732f32740c86..53c51231b31c 100644
--- a/include/drm/drm_dsc.h
+++ b/include/drm/drm_dsc.h
@@ -256,41 +256,42 @@ struct drm_dsc_config {
 	bool native_420;
 	/**
 	 * @second_line_bpg_offset:
 	 * Additional bits/grp for seconnd line of slice for native 4:2:0
 	 */
 	u8 second_line_bpg_offset;
 	/**
 	 * @nsl_bpg_offset:
 	 * Num of bits deallocated for each grp that is not in second line of
 	 * slice
 	 */
 	u16 nsl_bpg_offset;
 	/**
 	 * @second_line_offset_adj:
 	 * Offset adjustment for second line in Native 4:2:0 mode
 	 */
 	u16 second_line_offset_adj;
 };
 
 /**
- * struct picture_parameter_set - Represents 128 bytes of Picture Parameter Set
+ * struct drm_dsc_picture_parameter_set - Represents 128 bytes of
+ * 	Picture Parameter Set
  *
  * The VESA DSC standard defines picture parameter set (PPS) which display
  * stream compression encoders must communicate to decoders.
  * The PPS is encapsulated in 128 bytes (PPS 0 through PPS 127). The fields in
  * this structure are as per Table 4.1 in Vesa DSC specification v1.1/v1.2.
  * The PPS fields that span over more than a byte should be stored in Big Endian
  * format.
  */
 struct drm_dsc_picture_parameter_set {
 	/**
 	 * @dsc_version:
 	 * PPS0[3:0] - dsc_version_minor: Contains Minor version of DSC
 	 * PPS0[7:4] - dsc_version_major: Contains major version of DSC
 	 */
 	u8 dsc_version;
 	/**
 	 * @pps_identifier:
 	 * PPS1[7:0] - Application specific identifier that can be
 	 * used to differentiate between different PPS tables.
 	 */
diff --git a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h
index c0d28ba0f5c9..a4bac02249c2 100644
--- a/include/drm/drm_gem_vram_helper.h
+++ b/include/drm/drm_gem_vram_helper.h
@@ -49,54 +49,54 @@ struct vm_area_struct;
  * drm_gem_vram_vmap() and drm_gem_vram_vunmap().
  */
 struct drm_gem_vram_object {
 	struct ttm_buffer_object bo;
 	struct dma_buf_map map;
 
 	/**
 	 * @vmap_use_count:
 	 *
 	 * Reference count on the virtual address.
 	 * The address are un-mapped when the count reaches zero.
 	 */
 	unsigned int vmap_use_count;
 
 	/* Supported placements are %TTM_PL_VRAM and %TTM_PL_SYSTEM */
 	struct ttm_placement placement;
 	struct ttm_place placements[2];
 };
 
 /**
- * Returns the container of type &struct drm_gem_vram_object
- * for field bo.
+ * drm_gem_vram_of_bo - Returns the container of type
+ * &struct drm_gem_vram_object for field bo.
  * @bo:		the VRAM buffer object
  * Returns:	The containing GEM VRAM object
  */
 static inline struct drm_gem_vram_object *drm_gem_vram_of_bo(
 	struct ttm_buffer_object *bo)
 {
 	return container_of(bo, struct drm_gem_vram_object, bo);
 }
 
 /**
- * Returns the container of type &struct drm_gem_vram_object
- * for field gem.
+ * drm_gem_vram_of_gem - Returns the container of type
+ * &struct drm_gem_vram_object for field gem.
  * @gem:	the GEM object
  * Returns:	The containing GEM VRAM object
  */
 static inline struct drm_gem_vram_object *drm_gem_vram_of_gem(
 	struct drm_gem_object *gem)
 {
 	return container_of(gem, struct drm_gem_vram_object, bo.base);
 }
 
 struct drm_gem_vram_object *drm_gem_vram_create(struct drm_device *dev,
 						size_t size,
 						unsigned long pg_align);
 void drm_gem_vram_put(struct drm_gem_vram_object *gbo);
 u64 drm_gem_vram_mmap_offset(struct drm_gem_vram_object *gbo);
 s64 drm_gem_vram_offset(struct drm_gem_vram_object *gbo);
 int drm_gem_vram_pin(struct drm_gem_vram_object *gbo, unsigned long pl_flag);
 int drm_gem_vram_unpin(struct drm_gem_vram_object *gbo);
 int drm_gem_vram_vmap(struct drm_gem_vram_object *gbo, struct dma_buf_map *map);
 void drm_gem_vram_vunmap(struct drm_gem_vram_object *gbo, struct dma_buf_map *map);
 
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 06/27] HSI: fix a kernel-doc markup
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (4 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 05/27] drm: fix some " Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 07/27] IB: fix kernel-doc markups Mauro Carvalho Chehab
                   ` (21 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Sebastian Reichel
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-kernel

A function has a different name between their prototype
and its kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/hsi/hsi_core.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/hsi/hsi_core.c b/drivers/hsi/hsi_core.c
index 47f0208aa7c3..c3fb5beb846e 100644
--- a/drivers/hsi/hsi_core.c
+++ b/drivers/hsi/hsi_core.c
@@ -335,41 +335,41 @@ static int hsi_remove_port(struct device *dev, void *data __maybe_unused)
 	device_for_each_child(dev, NULL, hsi_remove_client);
 	device_unregister(dev);
 
 	return 0;
 }
 
 static void hsi_controller_release(struct device *dev)
 {
 	struct hsi_controller *hsi = to_hsi_controller(dev);
 
 	kfree(hsi->port);
 	kfree(hsi);
 }
 
 static void hsi_port_release(struct device *dev)
 {
 	kfree(to_hsi_port(dev));
 }
 
 /**
- * hsi_unregister_port - Unregister an HSI port
+ * hsi_port_unregister_clients - Unregister an HSI port
  * @port: The HSI port to unregister
  */
 void hsi_port_unregister_clients(struct hsi_port *port)
 {
 	device_for_each_child(&port->device, NULL, hsi_remove_client);
 }
 EXPORT_SYMBOL_GPL(hsi_port_unregister_clients);
 
 /**
  * hsi_unregister_controller - Unregister an HSI controller
  * @hsi: The HSI controller to register
  */
 void hsi_unregister_controller(struct hsi_controller *hsi)
 {
 	device_for_each_child(&hsi->device, NULL, hsi_remove_port);
 	device_unregister(&hsi->device);
 }
 EXPORT_SYMBOL_GPL(hsi_unregister_controller);
 
 /**
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 07/27] IB: fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (5 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 06/27] HSI: fix a kernel-doc markup Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:36   ` Gustavo A. R. Silva
  2020-11-23 23:45   ` Jason Gunthorpe
  2020-11-16 10:18 ` [PATCH v4 08/27] parport: fix a kernel-doc markup Mauro Carvalho Chehab
                   ` (20 subsequent siblings)
  27 siblings, 2 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Gustavo A. R. Silva, Håkon Bugge,
	Jonathan Corbet, Bart Van Assche, Chuck Lever, Danit Goldberg,
	Dennis Dalessandro, Divya Indi, Doug Ledford, Gal Pressman,
	Jason Gunthorpe, Leon Romanovsky, Maor Gottlieb, Max Gurtovoy,
	Mike Marciniszyn, Moni Shoua, Or Gerlitz, Parav Pandit,
	Sagi Grimberg, Ursula Braun, Xi Wang, Yamin Friedman,
	linux-kernel, linux-rdma, target-devel

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

Others need to be fixed, as kernel-doc markups should use this format:
        identifier - description

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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 +-
 drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h     |  2 +-
 .../infiniband/ulp/opa_vnic/opa_vnic_vema_iface.c    |  2 +-
 drivers/infiniband/ulp/srpt/ib_srpt.h                |  2 +-
 include/rdma/ib_verbs.h                              | 11 +++++++++++
 13 files changed, 36 insertions(+), 23 deletions(-)

diff --git a/drivers/infiniband/core/cm.c b/drivers/infiniband/core/cm.c
index 020136497459..9dc69cd1d696 100644
--- a/drivers/infiniband/core/cm.c
+++ b/drivers/infiniband/core/cm.c
@@ -1234,41 +1234,42 @@ int ib_cm_listen(struct ib_cm_id *cm_id, __be64 service_id, __be64 service_mask)
 
 	ret = cm_init_listen(cm_id_priv, service_id, service_mask);
 	if (ret)
 		goto out;
 
 	if (!cm_insert_listen(cm_id_priv, NULL)) {
 		ret = -EBUSY;
 		goto out;
 	}
 
 	cm_id_priv->id.state = IB_CM_LISTEN;
 	ret = 0;
 
 out:
 	spin_unlock_irqrestore(&cm_id_priv->lock, flags);
 	return ret;
 }
 EXPORT_SYMBOL(ib_cm_listen);
 
 /**
- * Create a new listening ib_cm_id and listen on the given service ID.
+ * ib_cm_insert_listen - Create a new listening ib_cm_id and listen on
+ *			 the given service ID.
  *
  * If there's an existing ID listening on that same device and service ID,
  * return it.
  *
  * @device: Device associated with the cm_id.  All related communication will
  * be associated with the specified device.
  * @cm_handler: Callback invoked to notify the user of CM events.
  * @service_id: Service identifier matched against incoming connection
  *   and service ID resolution requests.  The service ID should be specified
  *   network-byte order.  If set to IB_CM_ASSIGN_SERVICE_ID, the CM will
  *   assign a service ID to the caller.
  *
  * Callers should call ib_destroy_cm_id when done with the listener ID.
  */
 struct ib_cm_id *ib_cm_insert_listen(struct ib_device *device,
 				     ib_cm_handler cm_handler,
 				     __be64 service_id)
 {
 	struct cm_id_private *listen_id_priv;
 	struct cm_id_private *cm_id_priv;
@@ -1747,41 +1748,41 @@ static void cm_format_paths_from_req(struct cm_req_msg *req_msg,
 
 static u16 cm_get_bth_pkey(struct cm_work *work)
 {
 	struct ib_device *ib_dev = work->port->cm_dev->ib_device;
 	u8 port_num = work->port->port_num;
 	u16 pkey_index = work->mad_recv_wc->wc->pkey_index;
 	u16 pkey;
 	int ret;
 
 	ret = ib_get_cached_pkey(ib_dev, port_num, pkey_index, &pkey);
 	if (ret) {
 		dev_warn_ratelimited(&ib_dev->dev, "ib_cm: Couldn't retrieve pkey for incoming request (port %d, pkey index %d). %d\n",
 				     port_num, pkey_index, ret);
 		return 0;
 	}
 
 	return pkey;
 }
 
 /**
- * Convert OPA SGID to IB SGID
+ * cm_opa_to_ib_sgid - Convert OPA SGID to IB SGID
  * ULPs (such as IPoIB) do not understand OPA GIDs and will
  * reject them as the local_gid will not match the sgid. Therefore,
  * change the pathrec's SGID to an IB SGID.
  *
  * @work: Work completion
  * @path: Path record
  */
 static void cm_opa_to_ib_sgid(struct cm_work *work,
 			      struct sa_path_rec *path)
 {
 	struct ib_device *dev = work->port->cm_dev->ib_device;
 	u8 port_num = work->port->port_num;
 
 	if (rdma_cap_opa_ah(dev, port_num) &&
 	    (ib_is_opa_gid(&path->sgid))) {
 		union ib_gid sgid;
 
 		if (rdma_query_gid(dev, port_num, 0, &sgid)) {
 			dev_warn(&dev->dev,
 				 "Error updating sgid in CM request\n");
diff --git a/drivers/infiniband/core/cq.c b/drivers/infiniband/core/cq.c
index 12ebacf52958..d4248bbe74da 100644
--- a/drivers/infiniband/core/cq.c
+++ b/drivers/infiniband/core/cq.c
@@ -106,41 +106,41 @@ static int __ib_process_cq(struct ib_cq *cq, int budget, struct ib_wc *wcs,
 					budget - completed), wcs)) > 0) {
 		for (i = 0; i < n; i++) {
 			struct ib_wc *wc = &wcs[i];
 
 			if (wc->wr_cqe)
 				wc->wr_cqe->done(cq, wc);
 			else
 				WARN_ON_ONCE(wc->status == IB_WC_SUCCESS);
 		}
 
 		completed += n;
 
 		if (n != batch || (budget != -1 && completed >= budget))
 			break;
 	}
 
 	return completed;
 }
 
 /**
- * ib_process_direct_cq - process a CQ in caller context
+ * ib_process_cq_direct - process a CQ in caller context
  * @cq:		CQ to process
  * @budget:	number of CQEs to poll for
  *
  * This function is used to process all outstanding CQ entries.
  * It does not offload CQ processing to a different context and does
  * not ask for completion interrupts from the HCA.
  * Using direct processing on CQ with non IB_POLL_DIRECT type may trigger
  * concurrent processing.
  *
  * Note: do not pass -1 as %budget unless it is guaranteed that the number
  * of completions that will be processed is small.
  */
 int ib_process_cq_direct(struct ib_cq *cq, int budget)
 {
 	struct ib_wc wcs[IB_POLL_BATCH_DIRECT];
 
 	return __ib_process_cq(cq, budget, wcs, IB_POLL_BATCH_DIRECT);
 }
 EXPORT_SYMBOL(ib_process_cq_direct);
 
@@ -180,41 +180,41 @@ static void ib_cq_poll_work(struct work_struct *work)
 {
 	struct ib_cq *cq = container_of(work, struct ib_cq, work);
 	int completed;
 
 	completed = __ib_process_cq(cq, IB_POLL_BUDGET_WORKQUEUE, cq->wc,
 				    IB_POLL_BATCH);
 	if (completed >= IB_POLL_BUDGET_WORKQUEUE ||
 	    ib_req_notify_cq(cq, IB_POLL_FLAGS) > 0)
 		queue_work(cq->comp_wq, &cq->work);
 	else if (cq->dim)
 		rdma_dim(cq->dim, completed);
 }
 
 static void ib_cq_completion_workqueue(struct ib_cq *cq, void *private)
 {
 	trace_cq_schedule(cq);
 	queue_work(cq->comp_wq, &cq->work);
 }
 
 /**
- * __ib_alloc_cq        allocate a completion queue
+ * __ib_alloc_cq - allocate a completion queue
  * @dev:		device to allocate the CQ for
  * @private:		driver private data, accessible from cq->cq_context
  * @nr_cqe:		number of CQEs to allocate
  * @comp_vector:	HCA completion vectors for this CQ
  * @poll_ctx:		context to poll the CQ from.
  * @caller:		module owner name.
  *
  * This is the proper interface to allocate a CQ for in-kernel users. A
  * CQ allocated with this interface will automatically be polled from the
  * specified context. The ULP must use wr->wr_cqe instead of wr->wr_id
  * to use this CQ abstraction.
  */
 struct ib_cq *__ib_alloc_cq(struct ib_device *dev, void *private, int nr_cqe,
 			    int comp_vector, enum ib_poll_context poll_ctx,
 			    const char *caller)
 {
 	struct ib_cq_init_attr cq_attr = {
 		.cqe		= nr_cqe,
 		.comp_vector	= comp_vector,
 	};
diff --git a/drivers/infiniband/core/iwpm_util.h b/drivers/infiniband/core/iwpm_util.h
index 1bf87d9fd0bd..eeb8e6010907 100644
--- a/drivers/infiniband/core/iwpm_util.h
+++ b/drivers/infiniband/core/iwpm_util.h
@@ -124,41 +124,41 @@ void iwpm_free_nlmsg_request(struct kref *kref);
 struct iwpm_nlmsg_request *iwpm_find_nlmsg_request(__u32 echo_seq);
 
 /**
  * iwpm_wait_complete_req - Block while servicing the netlink request
  * @nlmsg_request: Netlink message request to service
  *
  * Wakes up, after the request is completed or expired
  * Returns 0 if the request is complete without error
  */
 int iwpm_wait_complete_req(struct iwpm_nlmsg_request *nlmsg_request);
 
 /**
  * iwpm_get_nlmsg_seq - Get the sequence number for a netlink
  *			message to send to the port mapper
  *
  * Returns the sequence number for the netlink message.
  */
 int iwpm_get_nlmsg_seq(void);
 
 /**
- * iwpm_add_reminfo - Add remote address info of the connecting peer
+ * iwpm_add_remote_info - Add remote address info of the connecting peer
  *                    to the remote info hash table
  * @reminfo: The remote info to be added
  */
 void iwpm_add_remote_info(struct iwpm_remote_info *reminfo);
 
 /**
  * iwpm_valid_client - Check if the port mapper client is valid
  * @nl_client: The index of the netlink client
  *
  * Valid clients need to call iwpm_init() before using
  * the port mapper
  */
 int iwpm_valid_client(u8 nl_client);
 
 /**
  * iwpm_set_valid - Set the port mapper client to valid or not
  * @nl_client: The index of the netlink client
  * @valid: 1 if valid or 0 if invalid
  */
 void iwpm_set_valid(u8 nl_client, int valid);
diff --git a/drivers/infiniband/core/sa_query.c b/drivers/infiniband/core/sa_query.c
index 8c930bf1df89..89a831fa1885 100644
--- a/drivers/infiniband/core/sa_query.c
+++ b/drivers/infiniband/core/sa_query.c
@@ -1418,41 +1418,42 @@ static bool ib_sa_opa_pathrecord_support(struct ib_sa_client *client,
 	port = &sa_dev->port[port_num - sa_dev->start_port];
 	spin_lock_irqsave(&port->classport_lock, flags);
 	if (!port->classport_info.valid)
 		goto ret;
 
 	if (port->classport_info.data.type == RDMA_CLASS_PORT_INFO_OPA)
 		ret = opa_get_cpi_capmask2(&port->classport_info.data.opa) &
 			OPA_CLASS_PORT_INFO_PR_SUPPORT;
 ret:
 	spin_unlock_irqrestore(&port->classport_lock, flags);
 	return ret;
 }
 
 enum opa_pr_supported {
 	PR_NOT_SUPPORTED,
 	PR_OPA_SUPPORTED,
 	PR_IB_SUPPORTED
 };
 
 /**
- * Check if current PR query can be an OPA query.
+ * opa_pr_query_possible - Check if current PR query can be an OPA query.
+ *
  * Retuns PR_NOT_SUPPORTED if a path record query is not
  * possible, PR_OPA_SUPPORTED if an OPA path record query
  * is possible and PR_IB_SUPPORTED if an IB path record
  * query is possible.
  */
 static int opa_pr_query_possible(struct ib_sa_client *client,
 				 struct ib_sa_device *sa_dev,
 				 struct ib_device *device, u8 port_num,
 				 struct sa_path_rec *rec)
 {
 	struct ib_port_attr port_attr;
 
 	if (ib_query_port(device, port_num, &port_attr))
 		return PR_NOT_SUPPORTED;
 
 	if (ib_sa_opa_pathrecord_support(client, sa_dev, port_num))
 		return PR_OPA_SUPPORTED;
 
 	if (port_attr.lid >= be16_to_cpu(IB_MULTICAST_LID_BASE))
 		return PR_NOT_SUPPORTED;
diff --git a/drivers/infiniband/core/verbs.c b/drivers/infiniband/core/verbs.c
index ab1e6048685e..9cecdb744c83 100644
--- a/drivers/infiniband/core/verbs.c
+++ b/drivers/infiniband/core/verbs.c
@@ -227,41 +227,41 @@ rdma_node_get_transport(unsigned int node_type)
 }
 EXPORT_SYMBOL(rdma_node_get_transport);
 
 enum rdma_link_layer rdma_port_get_link_layer(struct ib_device *device, u8 port_num)
 {
 	enum rdma_transport_type lt;
 	if (device->ops.get_link_layer)
 		return device->ops.get_link_layer(device, port_num);
 
 	lt = rdma_node_get_transport(device->node_type);
 	if (lt == RDMA_TRANSPORT_IB)
 		return IB_LINK_LAYER_INFINIBAND;
 
 	return IB_LINK_LAYER_ETHERNET;
 }
 EXPORT_SYMBOL(rdma_port_get_link_layer);
 
 /* Protection domains */
 
 /**
- * ib_alloc_pd - Allocates an unused protection domain.
+ * __ib_alloc_pd - Allocates an unused protection domain.
  * @device: The device on which to allocate the protection domain.
  * @flags: protection domain flags
  * @caller: caller's build-time module name
  *
  * A protection domain object provides an association between QPs, shared
  * receive queues, address handles, memory regions, and memory windows.
  *
  * Every PD has a local_dma_lkey which can be used as the lkey value for local
  * memory operations.
  */
 struct ib_pd *__ib_alloc_pd(struct ib_device *device, unsigned int flags,
 		const char *caller)
 {
 	struct ib_pd *pd;
 	int mr_access_flags = 0;
 	int ret;
 
 	pd = rdma_zalloc_drv_obj(device, ib_pd);
 	if (!pd)
 		return ERR_PTR(-ENOMEM);
@@ -1648,41 +1648,41 @@ static int ib_resolve_eth_dmac(struct ib_device *device,
 			memcpy(&addr, ah_attr->grh.dgid.raw + 12, 4);
 			ip_eth_mc_map(addr, (char *)ah_attr->roce.dmac);
 		} else {
 			ipv6_eth_mc_map((struct in6_addr *)ah_attr->grh.dgid.raw,
 					(char *)ah_attr->roce.dmac);
 		}
 	} else {
 		ret = ib_resolve_unicast_gid_dmac(device, ah_attr);
 	}
 	return ret;
 }
 
 static bool is_qp_type_connected(const struct ib_qp *qp)
 {
 	return (qp->qp_type == IB_QPT_UC ||
 		qp->qp_type == IB_QPT_RC ||
 		qp->qp_type == IB_QPT_XRC_INI ||
 		qp->qp_type == IB_QPT_XRC_TGT);
 }
 
-/**
+/*
  * IB core internal function to perform QP attributes modification.
  */
 static int _ib_modify_qp(struct ib_qp *qp, struct ib_qp_attr *attr,
 			 int attr_mask, struct ib_udata *udata)
 {
 	u8 port = attr_mask & IB_QP_PORT ? attr->port_num : qp->port;
 	const struct ib_gid_attr *old_sgid_attr_av;
 	const struct ib_gid_attr *old_sgid_attr_alt_av;
 	int ret;
 
 	attr->xmit_slave = NULL;
 	if (attr_mask & IB_QP_AV) {
 		ret = rdma_fill_sgid_attr(qp->device, &attr->ah_attr,
 					  &old_sgid_attr_av);
 		if (ret)
 			return ret;
 
 		if (attr->ah_attr.type == RDMA_AH_ATTR_TYPE_ROCE &&
 		    is_qp_type_connected(qp)) {
 			struct net_device *slave;
diff --git a/drivers/infiniband/sw/rdmavt/ah.c b/drivers/infiniband/sw/rdmavt/ah.c
index f9754dcd250b..480b621d1a9f 100644
--- a/drivers/infiniband/sw/rdmavt/ah.c
+++ b/drivers/infiniband/sw/rdmavt/ah.c
@@ -109,41 +109,41 @@ int rvt_create_ah(struct ib_ah *ibah, struct rdma_ah_init_attr *init_attr,
 
 	spin_lock_irqsave(&dev->n_ahs_lock, flags);
 	if (dev->n_ahs_allocated == dev->dparms.props.max_ah) {
 		spin_unlock_irqrestore(&dev->n_ahs_lock, flags);
 		return -ENOMEM;
 	}
 
 	dev->n_ahs_allocated++;
 	spin_unlock_irqrestore(&dev->n_ahs_lock, flags);
 
 	rdma_copy_ah_attr(&ah->attr, init_attr->ah_attr);
 
 	if (dev->driver_f.notify_new_ah)
 		dev->driver_f.notify_new_ah(ibah->device,
 					    init_attr->ah_attr, ah);
 
 	return 0;
 }
 
 /**
- * rvt_destory_ah - Destory an address handle
+ * rvt_destroy_ah - Destory an address handle
  * @ibah: address handle
  * @destroy_flags: destroy address handle flags (see enum rdma_destroy_ah_flags)
  * Return: 0 on success
  */
 int rvt_destroy_ah(struct ib_ah *ibah, u32 destroy_flags)
 {
 	struct rvt_dev_info *dev = ib_to_rvt(ibah->device);
 	struct rvt_ah *ah = ibah_to_rvtah(ibah);
 	unsigned long flags;
 
 	spin_lock_irqsave(&dev->n_ahs_lock, flags);
 	dev->n_ahs_allocated--;
 	spin_unlock_irqrestore(&dev->n_ahs_lock, flags);
 
 	rdma_destroy_ah_attr(&ah->attr);
 	return 0;
 }
 
 /**
  * rvt_modify_ah - modify an ah with given attrs
diff --git a/drivers/infiniband/sw/rdmavt/mcast.c b/drivers/infiniband/sw/rdmavt/mcast.c
index dd11c6fcd060..5233a63d99a6 100644
--- a/drivers/infiniband/sw/rdmavt/mcast.c
+++ b/drivers/infiniband/sw/rdmavt/mcast.c
@@ -37,85 +37,85 @@
  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *
  */
 
 #include <linux/slab.h>
 #include <linux/sched.h>
 #include <linux/rculist.h>
 #include <rdma/rdma_vt.h>
 #include <rdma/rdmavt_qp.h>
 
 #include "mcast.h"
 
 /**
- * rvt_driver_mcast - init resources for multicast
+ * rvt_driver_mcast_init - init resources for multicast
  * @rdi: rvt dev struct
  *
  * This is per device that registers with rdmavt
  */
 void rvt_driver_mcast_init(struct rvt_dev_info *rdi)
 {
 	/*
 	 * Anything that needs setup for multicast on a per driver or per rdi
 	 * basis should be done in here.
 	 */
 	spin_lock_init(&rdi->n_mcast_grps_lock);
 }
 
 /**
- * mcast_qp_alloc - alloc a struct to link a QP to mcast GID struct
+ * rvt_mcast_qp_alloc - alloc a struct to link a QP to mcast GID struct
  * @qp: the QP to link
  */
 static struct rvt_mcast_qp *rvt_mcast_qp_alloc(struct rvt_qp *qp)
 {
 	struct rvt_mcast_qp *mqp;
 
 	mqp = kmalloc(sizeof(*mqp), GFP_KERNEL);
 	if (!mqp)
 		goto bail;
 
 	mqp->qp = qp;
 	rvt_get_qp(qp);
 
 bail:
 	return mqp;
 }
 
 static void rvt_mcast_qp_free(struct rvt_mcast_qp *mqp)
 {
 	struct rvt_qp *qp = mqp->qp;
 
 	/* Notify hfi1_destroy_qp() if it is waiting. */
 	rvt_put_qp(qp);
 
 	kfree(mqp);
 }
 
 /**
- * mcast_alloc - allocate the multicast GID structure
+ * rvt_mcast_alloc - allocate the multicast GID structure
  * @mgid: the multicast GID
  * @lid: the muilticast LID (host order)
  *
  * A list of QPs will be attached to this structure.
  */
 static struct rvt_mcast *rvt_mcast_alloc(union ib_gid *mgid, u16 lid)
 {
 	struct rvt_mcast *mcast;
 
 	mcast = kzalloc(sizeof(*mcast), GFP_KERNEL);
 	if (!mcast)
 		goto bail;
 
 	mcast->mcast_addr.mgid = *mgid;
 	mcast->mcast_addr.lid = lid;
 
 	INIT_LIST_HEAD(&mcast->qp_list);
 	init_waitqueue_head(&mcast->wait);
 	atomic_set(&mcast->refcount, 0);
 
@@ -164,41 +164,41 @@ struct rvt_mcast *rvt_mcast_find(struct rvt_ibport *ibp, union ib_gid *mgid,
 			     sizeof(*mgid));
 		if (ret < 0) {
 			n = n->rb_left;
 		} else if (ret > 0) {
 			n = n->rb_right;
 		} else {
 			/* MGID/MLID must match */
 			if (mcast->mcast_addr.lid == lid) {
 				atomic_inc(&mcast->refcount);
 				found = mcast;
 			}
 			break;
 		}
 	}
 	spin_unlock_irqrestore(&ibp->lock, flags);
 	return found;
 }
 EXPORT_SYMBOL(rvt_mcast_find);
 
 /**
- * mcast_add - insert mcast GID into table and attach QP struct
+ * rvt_mcast_add - insert mcast GID into table and attach QP struct
  * @mcast: the mcast GID table
  * @mqp: the QP to attach
  *
  * Return: zero if both were added.  Return EEXIST if the GID was already in
  * the table but the QP was added.  Return ESRCH if the QP was already
  * attached and neither structure was added. Return EINVAL if the MGID was
  * found, but the MLID did NOT match.
  */
 static int rvt_mcast_add(struct rvt_dev_info *rdi, struct rvt_ibport *ibp,
 			 struct rvt_mcast *mcast, struct rvt_mcast_qp *mqp)
 {
 	struct rb_node **n = &ibp->mcast_tree.rb_node;
 	struct rb_node *pn = NULL;
 	int ret;
 
 	spin_lock_irq(&ibp->lock);
 
 	while (*n) {
 		struct rvt_mcast *tmcast;
 		struct rvt_mcast_qp *p;
@@ -409,35 +409,35 @@ int rvt_detach_mcast(struct ib_qp *ibqp, union ib_gid *gid, u16 lid)
 	/*
 	 * Wait for any list walkers to finish before freeing the
 	 * list element.
 	 */
 	wait_event(mcast->wait, atomic_read(&mcast->refcount) <= 1);
 	rvt_mcast_qp_free(delp);
 
 	if (last) {
 		atomic_dec(&mcast->refcount);
 		wait_event(mcast->wait, !atomic_read(&mcast->refcount));
 		rvt_mcast_free(mcast);
 		spin_lock_irq(&rdi->n_mcast_grps_lock);
 		rdi->n_mcast_grps_allocated--;
 		spin_unlock_irq(&rdi->n_mcast_grps_lock);
 	}
 
 	return 0;
 }
 
 /**
- *rvt_mast_tree_empty - determine if any qps are attached to any mcast group
- *@rdi: rvt dev struct
+ * rvt_mcast_tree_empty - determine if any qps are attached to any mcast group
+ * @rdi: rvt dev struct
  *
  * Return: in use count
  */
 int rvt_mcast_tree_empty(struct rvt_dev_info *rdi)
 {
 	int i;
 	int in_use = 0;
 
 	for (i = 0; i < rdi->dparms.nports; i++)
 		if (rdi->ports[i]->mcast_tree.rb_node)
 			in_use++;
 	return in_use;
 }
diff --git a/drivers/infiniband/sw/rdmavt/qp.c b/drivers/infiniband/sw/rdmavt/qp.c
index e9db6bf10618..22fa9bde5419 100644
--- a/drivers/infiniband/sw/rdmavt/qp.c
+++ b/drivers/infiniband/sw/rdmavt/qp.c
@@ -1810,41 +1810,41 @@ int rvt_query_qp(struct ib_qp *ibqp, struct ib_qp_attr *attr,
 	attr->alt_port_num =
 		rdma_ah_get_port_num(&qp->alt_ah_attr);
 	attr->alt_timeout = qp->alt_timeout;
 
 	init_attr->event_handler = qp->ibqp.event_handler;
 	init_attr->qp_context = qp->ibqp.qp_context;
 	init_attr->send_cq = qp->ibqp.send_cq;
 	init_attr->recv_cq = qp->ibqp.recv_cq;
 	init_attr->srq = qp->ibqp.srq;
 	init_attr->cap = attr->cap;
 	if (qp->s_flags & RVT_S_SIGNAL_REQ_WR)
 		init_attr->sq_sig_type = IB_SIGNAL_REQ_WR;
 	else
 		init_attr->sq_sig_type = IB_SIGNAL_ALL_WR;
 	init_attr->qp_type = qp->ibqp.qp_type;
 	init_attr->port_num = qp->port_num;
 	return 0;
 }
 
 /**
- * rvt_post_receive - post a receive on a QP
+ * rvt_post_recv - post a receive on a QP
  * @ibqp: the QP to post the receive on
  * @wr: the WR to post
  * @bad_wr: the first bad WR is put here
  *
  * This may be called from interrupt context.
  *
  * Return: 0 on success otherwise errno
  */
 int rvt_post_recv(struct ib_qp *ibqp, const struct ib_recv_wr *wr,
 		  const struct ib_recv_wr **bad_wr)
 {
 	struct rvt_qp *qp = ibqp_to_rvtqp(ibqp);
 	struct rvt_krwq *wq = qp->r_rq.kwq;
 	unsigned long flags;
 	int qp_err_flush = (ib_rvt_state_ops[qp->state] & RVT_FLUSH_RECV) &&
 				!qp->ibqp.srq;
 
 	/* Check that state is OK to post receive. */
 	if (!(ib_rvt_state_ops[qp->state] & RVT_POST_RECV_OK) || !wq) {
 		*bad_wr = wr;
@@ -2232,41 +2232,41 @@ int rvt_post_send(struct ib_qp *ibqp, const struct ib_send_wr *wr,
 			goto bail;
 		}
 		nreq++;
 	}
 bail:
 	spin_unlock_irqrestore(&qp->s_hlock, flags);
 	if (nreq) {
 		/*
 		 * Only call do_send if there is exactly one packet, and the
 		 * driver said it was ok.
 		 */
 		if (nreq == 1 && call_send)
 			rdi->driver_f.do_send(qp);
 		else
 			rdi->driver_f.schedule_send_no_lock(qp);
 	}
 	return err;
 }
 
 /**
- * rvt_post_srq_receive - post a receive on a shared receive queue
+ * rvt_post_srq_recv - post a receive on a shared receive queue
  * @ibsrq: the SRQ to post the receive on
  * @wr: the list of work requests to post
  * @bad_wr: A pointer to the first WR to cause a problem is put here
  *
  * This may be called from interrupt context.
  *
  * Return: 0 on success else errno
  */
 int rvt_post_srq_recv(struct ib_srq *ibsrq, const struct ib_recv_wr *wr,
 		      const struct ib_recv_wr **bad_wr)
 {
 	struct rvt_srq *srq = ibsrq_to_rvtsrq(ibsrq);
 	struct rvt_krwq *wq;
 	unsigned long flags;
 
 	for (; wr; wr = wr->next) {
 		struct rvt_rwqe *wqe;
 		u32 next;
 		int i;
 
@@ -2484,41 +2484,41 @@ int rvt_get_rwqe(struct rvt_qp *qp, bool wr_id_only)
 				struct ib_event ev;
 
 				srq->limit = 0;
 				spin_unlock_irqrestore(&rq->kwq->c_lock, flags);
 				ev.device = qp->ibqp.device;
 				ev.element.srq = qp->ibqp.srq;
 				ev.event = IB_EVENT_SRQ_LIMIT_REACHED;
 				handler(&ev, srq->ibsrq.srq_context);
 				goto bail;
 			}
 		}
 	}
 unlock:
 	spin_unlock_irqrestore(&rq->kwq->c_lock, flags);
 bail:
 	return ret;
 }
 EXPORT_SYMBOL(rvt_get_rwqe);
 
 /**
- * qp_comm_est - handle trap with QP established
+ * rvt_comm_est - handle trap with QP established
  * @qp: the QP
  */
 void rvt_comm_est(struct rvt_qp *qp)
 {
 	qp->r_flags |= RVT_R_COMM_EST;
 	if (qp->ibqp.event_handler) {
 		struct ib_event ev;
 
 		ev.device = qp->ibqp.device;
 		ev.element.qp = &qp->ibqp;
 		ev.event = IB_EVENT_COMM_EST;
 		qp->ibqp.event_handler(&ev, qp->ibqp.qp_context);
 	}
 }
 EXPORT_SYMBOL(rvt_comm_est);
 
 void rvt_rc_error(struct rvt_qp *qp, enum ib_wc_status err)
 {
 	unsigned long flags;
 	int lastwqe;
@@ -2930,41 +2930,41 @@ void rvt_copy_sge(struct rvt_qp *qp, struct rvt_sge_state *ss,
 		in_last = true;
 		length = 8;
 		goto again;
 	}
 }
 EXPORT_SYMBOL(rvt_copy_sge);
 
 static enum ib_wc_status loopback_qp_drop(struct rvt_ibport *rvp,
 					  struct rvt_qp *sqp)
 {
 	rvp->n_pkt_drops++;
 	/*
 	 * For RC, the requester would timeout and retry so
 	 * shortcut the timeouts and just signal too many retries.
 	 */
 	return sqp->ibqp.qp_type == IB_QPT_RC ?
 		IB_WC_RETRY_EXC_ERR : IB_WC_SUCCESS;
 }
 
 /**
- * ruc_loopback - handle UC and RC loopback requests
+ * rvt_ruc_loopback - handle UC and RC loopback requests
  * @sqp: the sending QP
  *
  * This is called from rvt_do_send() to forward a WQE addressed to the same HFI
  * Note that although we are single threaded due to the send engine, we still
  * have to protect against post_send().  We don't have to worry about
  * receive interrupts since this is a connected protocol and all packets
  * will pass through here.
  */
 void rvt_ruc_loopback(struct rvt_qp *sqp)
 {
 	struct rvt_ibport *rvp =  NULL;
 	struct rvt_dev_info *rdi = ib_to_rvt(sqp->ibqp.device);
 	struct rvt_qp *qp;
 	struct rvt_swqe *wqe;
 	struct rvt_sge *sge;
 	unsigned long flags;
 	struct ib_wc wc;
 	u64 sdata;
 	atomic64_t *maddr;
 	enum ib_wc_status send_status;
diff --git a/drivers/infiniband/ulp/iser/iscsi_iser.c b/drivers/infiniband/ulp/iser/iscsi_iser.c
index 3690e28cc7ea..1a459b35000c 100644
--- a/drivers/infiniband/ulp/iser/iscsi_iser.c
+++ b/drivers/infiniband/ulp/iser/iscsi_iser.c
@@ -722,41 +722,41 @@ iscsi_iser_set_param(struct iscsi_cls_conn *cls_conn,
 		if (value) {
 			iser_err("IFMarker wasn't negotiated to No\n");
 			return -EPROTO;
 		}
 		break;
 	case ISCSI_PARAM_OFMARKER_EN:
 		sscanf(buf, "%d", &value);
 		if (value) {
 			iser_err("OFMarker wasn't negotiated to No\n");
 			return -EPROTO;
 		}
 		break;
 	default:
 		return iscsi_set_param(cls_conn, param, buf, buflen);
 	}
 
 	return 0;
 }
 
 /**
- * iscsi_iser_set_param() - set class connection parameter
+ * iscsi_iser_conn_get_stats() - get iscsi connection statistics
  * @cls_conn:    iscsi class connection
  * @stats:       iscsi stats to output
  *
  * Output connection statistics.
  */
 static void
 iscsi_iser_conn_get_stats(struct iscsi_cls_conn *cls_conn, struct iscsi_stats *stats)
 {
 	struct iscsi_conn *conn = cls_conn->dd_data;
 
 	stats->txdata_octets = conn->txdata_octets;
 	stats->rxdata_octets = conn->rxdata_octets;
 	stats->scsicmd_pdus = conn->scsicmd_pdus_cnt;
 	stats->dataout_pdus = conn->dataout_pdus_cnt;
 	stats->scsirsp_pdus = conn->scsirsp_pdus_cnt;
 	stats->datain_pdus = conn->datain_pdus_cnt; /* always 0 */
 	stats->r2t_pdus = conn->r2t_pdus_cnt; /* always 0 */
 	stats->tmfcmd_pdus = conn->tmfcmd_pdus_cnt;
 	stats->tmfrsp_pdus = conn->tmfrsp_pdus_cnt;
 	stats->custom_length = 0;
diff --git a/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h b/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
index f64519872297..012fc27c5c93 100644
--- a/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
+++ b/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
@@ -420,41 +420,41 @@ struct opa_veswport_error_counters {
  * @opaportnum: physical port num (redundant on host)
  * @veswportindex: switch port index on opa port 0 based
  * @opcode: operation
  * @reserved: 32 bit for alignment
  *
  * The VNIC will send trap messages to the Ethernet manager to
  * inform it about changes to the VNIC config, behaviour etc.
  * This is the format of the trap payload.
  */
 struct opa_veswport_trap {
 	__be16  fabric_id;
 	__be16  veswid;
 	__be32  veswportnum;
 	__be16  opaportnum;
 	u8      veswportindex;
 	u8      opcode;
 	__be32  reserved;
 } __packed;
 
 /**
- * struct opa_vnic_iface_macs_entry - single entry in the mac list
+ * struct opa_vnic_iface_mac_entry - single entry in the mac list
  * @mac_addr: MAC address
  */
 struct opa_vnic_iface_mac_entry {
 	u8 mac_addr[ETH_ALEN];
 };
 
 /**
  * struct opa_veswport_iface_macs - Msg to set globally administered MAC
  * @start_idx: position of first entry (0 based)
  * @num_macs_in_msg: number of MACs in this message
  * @tot_macs_in_lst: The total number of MACs the agent has
  * @gen_count: gen_count to indicate change
  * @entry: The mac list entry
  *
  * Same attribute IDS and attribute modifiers as in locally administered
  * addresses used to set globally administered addresses
  */
 struct opa_veswport_iface_macs {
 	__be16 start_idx;
 	__be16 num_macs_in_msg;
diff --git a/drivers/infiniband/ulp/opa_vnic/opa_vnic_vema_iface.c b/drivers/infiniband/ulp/opa_vnic/opa_vnic_vema_iface.c
index 868b5aec1537..292c037aa239 100644
--- a/drivers/infiniband/ulp/opa_vnic/opa_vnic_vema_iface.c
+++ b/drivers/infiniband/ulp/opa_vnic/opa_vnic_vema_iface.c
@@ -57,41 +57,41 @@
  * @event: event to be reported
  *
  * This function calls vema api to sent a trap for the given event.
  */
 void opa_vnic_vema_report_event(struct opa_vnic_adapter *adapter, u8 event)
 {
 	struct __opa_veswport_info *info = &adapter->info;
 	struct __opa_veswport_trap trap_data;
 
 	trap_data.fabric_id = info->vesw.fabric_id;
 	trap_data.veswid = info->vesw.vesw_id;
 	trap_data.veswportnum = info->vport.port_num;
 	trap_data.opaportnum = adapter->port_num;
 	trap_data.veswportindex = adapter->vport_num;
 	trap_data.opcode = event;
 
 	opa_vnic_vema_send_trap(adapter, &trap_data, info->vport.encap_slid);
 }
 
 /**
- * opa_vnic_get_error_counters - get summary counters
+ * opa_vnic_get_summary_counters - get summary counters
  * @adapter: vnic port adapter
  * @cntrs: pointer to destination summary counters structure
  *
  * This function populates the summary counters that is maintained by the
  * given adapter to destination address provided.
  */
 void opa_vnic_get_summary_counters(struct opa_vnic_adapter *adapter,
 				   struct opa_veswport_summary_counters *cntrs)
 {
 	struct opa_vnic_stats vstats;
 	__be64 *dst;
 	u64 *src;
 
 	memset(&vstats, 0, sizeof(vstats));
 	spin_lock(&adapter->stats_lock);
 	adapter->rn_ops->ndo_get_stats64(adapter->netdev, &vstats.netstats);
 	spin_unlock(&adapter->stats_lock);
 
 	cntrs->vp_instance = cpu_to_be16(adapter->vport_num);
 	cntrs->vesw_id = cpu_to_be16(adapter->info.vesw.vesw_id);
diff --git a/drivers/infiniband/ulp/srpt/ib_srpt.h b/drivers/infiniband/ulp/srpt/ib_srpt.h
index bdeb010efee6..76e66f630c17 100644
--- a/drivers/infiniband/ulp/srpt/ib_srpt.h
+++ b/drivers/infiniband/ulp/srpt/ib_srpt.h
@@ -330,41 +330,41 @@ struct srpt_rdma_ch {
 	struct work_struct	release_work;
 };
 
 /**
  * struct srpt_nexus - I_T nexus
  * @rcu:       RCU head for this data structure.
  * @entry:     srpt_port.nexus_list list node.
  * @ch_list:   struct srpt_rdma_ch list. Protected by srpt_port.mutex.
  * @i_port_id: 128-bit initiator port identifier copied from SRP_LOGIN_REQ.
  * @t_port_id: 128-bit target port identifier copied from SRP_LOGIN_REQ.
  */
 struct srpt_nexus {
 	struct rcu_head		rcu;
 	struct list_head	entry;
 	struct list_head	ch_list;
 	u8			i_port_id[16];
 	u8			t_port_id[16];
 };
 
 /**
- * struct srpt_port_attib - attributes for SRPT port
+ * struct srpt_port_attrib - attributes for SRPT port
  * @srp_max_rdma_size: Maximum size of SRP RDMA transfers for new connections.
  * @srp_max_rsp_size: Maximum size of SRP response messages in bytes.
  * @srp_sq_size: Shared receive queue (SRQ) size.
  * @use_srq: Whether or not to use SRQ.
  */
 struct srpt_port_attrib {
 	u32			srp_max_rdma_size;
 	u32			srp_max_rsp_size;
 	u32			srp_sq_size;
 	bool			use_srq;
 };
 
 /**
  * struct srpt_tpg - information about a single "target portal group"
  * @entry:	Entry in @sport_id->tpg_list.
  * @sport_id:	Port name this TPG is associated with.
  * @tpg:	LIO TPG data structure.
  *
  * Zero or more target portal groups are associated with each port name
  * (srpt_port_id). With each TPG an ACL list is associated.
diff --git a/include/rdma/ib_verbs.h b/include/rdma/ib_verbs.h
index 9420827d2421..740984da3791 100644
--- a/include/rdma/ib_verbs.h
+++ b/include/rdma/ib_verbs.h
@@ -3416,40 +3416,51 @@ int ib_find_gid(struct ib_device *device, union ib_gid *gid,
 
 int ib_find_pkey(struct ib_device *device,
 		 u8 port_num, u16 pkey, u16 *index);
 
 enum ib_pd_flags {
 	/*
 	 * Create a memory registration for all memory in the system and place
 	 * the rkey for it into pd->unsafe_global_rkey.  This can be used by
 	 * ULPs to avoid the overhead of dynamic MRs.
 	 *
 	 * This flag is generally considered unsafe and must only be used in
 	 * extremly trusted environments.  Every use of it will log a warning
 	 * in the kernel log.
 	 */
 	IB_PD_UNSAFE_GLOBAL_RKEY	= 0x01,
 };
 
 struct ib_pd *__ib_alloc_pd(struct ib_device *device, unsigned int flags,
 		const char *caller);
 
+/**
+ * ib_alloc_pd - Allocates an unused protection domain.
+ * @device: The device on which to allocate the protection domain.
+ * @flags: protection domain flags
+ *
+ * A protection domain object provides an association between QPs, shared
+ * receive queues, address handles, memory regions, and memory windows.
+ *
+ * Every PD has a local_dma_lkey which can be used as the lkey value for local
+ * memory operations.
+ */
 #define ib_alloc_pd(device, flags) \
 	__ib_alloc_pd((device), (flags), KBUILD_MODNAME)
 
 int ib_dealloc_pd_user(struct ib_pd *pd, struct ib_udata *udata);
 
 /**
  * ib_dealloc_pd - Deallocate kernel PD
  * @pd: The protection domain
  *
  * NOTE: for user PD use ib_dealloc_pd_user with valid udata!
  */
 static inline void ib_dealloc_pd(struct ib_pd *pd)
 {
 	int ret = ib_dealloc_pd_user(pd, NULL);
 
 	WARN_ONCE(ret, "Destroy of kernel PD shouldn't fail");
 }
 
 enum rdma_create_ah_flags {
 	/* In a sleepable context */
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 08/27] parport: fix a kernel-doc markup
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (6 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 07/27] IB: fix kernel-doc markups Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 09/27] rapidio: fix kernel-doc a markup Mauro Carvalho Chehab
                   ` (19 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Sudip Mukherjee
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-kernel

The kernel-doc markup inside share.c is actually for
__parport_register_driver. The actual goal seems to be
to document parport_register_driver().

So, fix the existing markup and add a new one.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/parport/share.c |  2 +-
 include/linux/parport.h | 31 +++++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/drivers/parport/share.c b/drivers/parport/share.c
index 7fec4fefe151..62f8407923d4 100644
--- a/drivers/parport/share.c
+++ b/drivers/parport/share.c
@@ -226,41 +226,41 @@ static int port_check(struct device *dev, void *dev_drv)
 
 	/* only send ports, do not send other devices connected to bus */
 	if (is_parport(dev))
 		drv->match_port(to_parport_dev(dev));
 	return 0;
 }
 
 /*
  * Iterates through all the devices connected to the bus and return 1
  * if the device is a parallel port.
  */
 
 static int port_detect(struct device *dev, void *dev_drv)
 {
 	if (is_parport(dev))
 		return 1;
 	return 0;
 }
 
 /**
- *	parport_register_driver - register a parallel port device driver
+ *	__parport_register_driver - register a parallel port device driver
  *	@drv: structure describing the driver
  *	@owner: owner module of drv
  *	@mod_name: module name string
  *
  *	This can be called by a parallel port device driver in order
  *	to receive notifications about ports being found in the
  *	system, as well as ports no longer available.
  *
  *	If devmodel is true then the new device model is used
  *	for registration.
  *
  *	The @drv structure is allocated by the caller and must not be
  *	deallocated until after calling parport_unregister_driver().
  *
  *	If using the non device model:
  *	The driver's attach() function may block.  The port that
  *	attach() is given will be valid for the duration of the
  *	callback, but if the driver wants to take a copy of the
  *	pointer it must call parport_get_port() to do so.  Calling
  *	parport_register_device() on that port will do this for you.
diff --git a/include/linux/parport.h b/include/linux/parport.h
index 1fb508c19e83..f981f794c850 100644
--- a/include/linux/parport.h
+++ b/include/linux/parport.h
@@ -280,40 +280,71 @@ struct parport *parport_register_port(unsigned long base, int irq, int dma,
 
 /* Once a registered port is ready for high-level drivers to use, the
    low-level driver that registered it should announce it.  This will
    call the high-level drivers' attach() functions (after things like
    determining the IEEE 1284.3 topology of the port and collecting
    DeviceIDs). */
 void parport_announce_port (struct parport *port);
 
 /* Unregister a port. */
 extern void parport_remove_port(struct parport *port);
 
 /* Register a new high-level driver. */
 
 int __must_check __parport_register_driver(struct parport_driver *,
 					   struct module *,
 					   const char *mod_name);
 /*
  * parport_register_driver must be a macro so that KBUILD_MODNAME can
  * be expanded
  */
+
+/**
+ *	parport_register_driver - register a parallel port device driver
+ *	@driver: structure describing the driver
+ *
+ *	This can be called by a parallel port device driver in order
+ *	to receive notifications about ports being found in the
+ *	system, as well as ports no longer available.
+ *
+ *	If devmodel is true then the new device model is used
+ *	for registration.
+ *
+ *	The @driver structure is allocated by the caller and must not be
+ *	deallocated until after calling parport_unregister_driver().
+ *
+ *	If using the non device model:
+ *	The driver's attach() function may block.  The port that
+ *	attach() is given will be valid for the duration of the
+ *	callback, but if the driver wants to take a copy of the
+ *	pointer it must call parport_get_port() to do so.  Calling
+ *	parport_register_device() on that port will do this for you.
+ *
+ *	The driver's detach() function may block.  The port that
+ *	detach() is given will be valid for the duration of the
+ *	callback, but if the driver wants to take a copy of the
+ *	pointer it must call parport_get_port() to do so.
+ *
+ *
+ *	Returns 0 on success. The non device model will always succeeds.
+ *	but the new device model can fail and will return the error code.
+ **/
 #define parport_register_driver(driver)             \
 	__parport_register_driver(driver, THIS_MODULE, KBUILD_MODNAME)
 
 /* Unregister a high-level driver. */
 extern void parport_unregister_driver (struct parport_driver *);
 void parport_unregister_driver(struct parport_driver *);
 
 /* If parport_register_driver doesn't fit your needs, perhaps
  * parport_find_xxx does. */
 extern struct parport *parport_find_number (int);
 extern struct parport *parport_find_base (unsigned long);
 
 /* generic irq handler, if it suits your needs */
 extern irqreturn_t parport_irq_handler(int irq, void *dev_id);
 
 /* Reference counting for ports. */
 extern struct parport *parport_get_port (struct parport *);
 extern void parport_put_port (struct parport *);
 void parport_del_port(struct parport *);
 
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 09/27] rapidio: fix kernel-doc a markup
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (7 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 08/27] parport: fix a kernel-doc markup Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 10/27] video: fix some kernel-doc markups Mauro Carvalho Chehab
                   ` (18 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Alexandre Bounine, Matt Porter
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-kernel

Probaly this was due to a cut and paste issue.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/rapidio/rio.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/rapidio/rio.c b/drivers/rapidio/rio.c
index 606986c5ba2c..16b59b472b3d 100644
--- a/drivers/rapidio/rio.c
+++ b/drivers/rapidio/rio.c
@@ -732,41 +732,41 @@ EXPORT_SYMBOL_GPL(rio_unmap_inb_region);
  */
 int rio_map_outb_region(struct rio_mport *mport, u16 destid, u64 rbase,
 			u32 size, u32 rflags, dma_addr_t *local)
 {
 	int rc;
 	unsigned long flags;
 
 	if (!mport->ops->map_outb)
 		return -ENODEV;
 
 	spin_lock_irqsave(&rio_mmap_lock, flags);
 	rc = mport->ops->map_outb(mport, destid, rbase, size,
 		rflags, local);
 	spin_unlock_irqrestore(&rio_mmap_lock, flags);
 
 	return rc;
 }
 EXPORT_SYMBOL_GPL(rio_map_outb_region);
 
 /**
- * rio_unmap_inb_region -- Unmap the inbound memory region
+ * rio_unmap_outb_region -- Unmap the inbound memory region
  * @mport: Master port
  * @destid: destination id mapping points to
  * @rstart: RIO base address window translates to
  */
 void rio_unmap_outb_region(struct rio_mport *mport, u16 destid, u64 rstart)
 {
 	unsigned long flags;
 
 	if (!mport->ops->unmap_outb)
 		return;
 
 	spin_lock_irqsave(&rio_mmap_lock, flags);
 	mport->ops->unmap_outb(mport, destid, rstart);
 	spin_unlock_irqrestore(&rio_mmap_lock, flags);
 }
 EXPORT_SYMBOL_GPL(rio_unmap_outb_region);
 
 /**
  * rio_mport_get_physefb - Helper function that returns register offset
  *                      for Physical Layer Extended Features Block.
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 10/27] video: fix some kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (8 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 09/27] rapidio: fix kernel-doc a markup Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 15:36   ` Daniel Vetter
  2020-11-16 10:18 ` [PATCH v4 11/27] fs: fix " Mauro Carvalho Chehab
                   ` (17 subsequent siblings)
  27 siblings, 1 reply; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet,
	Bartlomiej Zolnierkiewicz, Bernard Zhao, Boris Brezillon,
	Daniel Vetter, Gwan-gyeong Mun, Laurent Pinchart, Sam Ravnborg,
	Sebastian Reichel, Thomas Zimmermann, dri-devel, linux-fbdev,
	linux-kernel

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/video/fbdev/core/fbcmap.c | 2 +-
 drivers/video/hdmi.c              | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/drivers/video/fbdev/core/fbcmap.c b/drivers/video/fbdev/core/fbcmap.c
index e5ae33c1a8e8..757d5c3f620b 100644
--- a/drivers/video/fbdev/core/fbcmap.c
+++ b/drivers/video/fbdev/core/fbcmap.c
@@ -59,41 +59,41 @@ static u16 blue16[] __read_mostly = {
     0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa,
     0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff
 };
 
 static const struct fb_cmap default_2_colors = {
     .len=2, .red=red2, .green=green2, .blue=blue2
 };
 static const struct fb_cmap default_8_colors = {
     .len=8, .red=red8, .green=green8, .blue=blue8
 };
 static const struct fb_cmap default_4_colors = {
     .len=4, .red=red4, .green=green4, .blue=blue4
 };
 static const struct fb_cmap default_16_colors = {
     .len=16, .red=red16, .green=green16, .blue=blue16
 };
 
 
 
 /**
- *	fb_alloc_cmap - allocate a colormap
+ *	fb_alloc_cmap_gfp - allocate a colormap
  *	@cmap: frame buffer colormap structure
  *	@len: length of @cmap
  *	@transp: boolean, 1 if there is transparency, 0 otherwise
  *	@flags: flags for kmalloc memory allocation
  *
  *	Allocates memory for a colormap @cmap.  @len is the
  *	number of entries in the palette.
  *
  *	Returns negative errno on error, or zero on success.
  *
  */
 
 int fb_alloc_cmap_gfp(struct fb_cmap *cmap, int len, int transp, gfp_t flags)
 {
 	int size = len * sizeof(u16);
 	int ret = -ENOMEM;
 
 	flags |= __GFP_NOWARN;
 
 	if (cmap->len != len) {
diff --git a/drivers/video/hdmi.c b/drivers/video/hdmi.c
index 1e4cb63d0d11..947be761dfa4 100644
--- a/drivers/video/hdmi.c
+++ b/drivers/video/hdmi.c
@@ -1675,41 +1675,42 @@ static int hdmi_audio_infoframe_unpack(struct hdmi_audio_infoframe *frame,
 
 	ret = hdmi_audio_infoframe_init(frame);
 	if (ret)
 		return ret;
 
 	ptr += HDMI_INFOFRAME_HEADER_SIZE;
 
 	frame->channels = ptr[0] & 0x7;
 	frame->coding_type = (ptr[0] >> 4) & 0xf;
 	frame->sample_size = ptr[1] & 0x3;
 	frame->sample_frequency = (ptr[1] >> 2) & 0x7;
 	frame->coding_type_ext = ptr[2] & 0x1f;
 	frame->channel_allocation = ptr[3];
 	frame->level_shift_value = (ptr[4] >> 3) & 0xf;
 	frame->downmix_inhibit = ptr[4] & 0x80 ? true : false;
 
 	return 0;
 }
 
 /**
- * hdmi_vendor_infoframe_unpack() - unpack binary buffer to a HDMI vendor infoframe
+ * hdmi_vendor_any_infoframe_unpack() - unpack binary buffer to a HDMI
+ * 	vendor infoframe
  * @frame: HDMI Vendor infoframe
  * @buffer: source buffer
  * @size: size of buffer
  *
  * Unpacks the information contained in binary @buffer into a structured
  * @frame of the HDMI Vendor information frame.
  * Also verifies the checksum as required by section 5.3.5 of the HDMI 1.4
  * specification.
  *
  * Returns 0 on success or a negative error code on failure.
  */
 static int
 hdmi_vendor_any_infoframe_unpack(union hdmi_vendor_any_infoframe *frame,
 				 const void *buffer, size_t size)
 {
 	const u8 *ptr = buffer;
 	size_t length;
 	int ret;
 	u8 hdmi_video_format;
 	struct hdmi_vendor_infoframe *hvf = &frame->hdmi;
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 11/27] fs: fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (9 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 10/27] video: fix some kernel-doc markups Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 12/27] jbd2: " Mauro Carvalho Chehab
                   ` (16 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Alexander Viro
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-fsdevel, linux-kernel

Two markups are at the wrong place. Kernel-doc only
support having the comment just before the identifier.

Also, some identifiers have different names between their
prototypes and the kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 fs/dcache.c   | 72 +++++++++++++++++++++++++--------------------------
 fs/inode.c    |  4 +--
 fs/seq_file.c |  5 ++--
 fs/super.c    | 12 ++++-----
 4 files changed, 47 insertions(+), 46 deletions(-)

diff --git a/fs/dcache.c b/fs/dcache.c
index ea0485861d93..6eabb48a49fc 100644
--- a/fs/dcache.c
+++ b/fs/dcache.c
@@ -439,85 +439,85 @@ static void d_shrink_add(struct dentry *dentry, struct list_head *list)
 static void d_lru_isolate(struct list_lru_one *lru, struct dentry *dentry)
 {
 	D_FLAG_VERIFY(dentry, DCACHE_LRU_LIST);
 	dentry->d_flags &= ~DCACHE_LRU_LIST;
 	this_cpu_dec(nr_dentry_unused);
 	if (d_is_negative(dentry))
 		this_cpu_dec(nr_dentry_negative);
 	list_lru_isolate(lru, &dentry->d_lru);
 }
 
 static void d_lru_shrink_move(struct list_lru_one *lru, struct dentry *dentry,
 			      struct list_head *list)
 {
 	D_FLAG_VERIFY(dentry, DCACHE_LRU_LIST);
 	dentry->d_flags |= DCACHE_SHRINK_LIST;
 	if (d_is_negative(dentry))
 		this_cpu_dec(nr_dentry_negative);
 	list_lru_isolate_move(lru, &dentry->d_lru, list);
 }
 
-/**
- * d_drop - drop a dentry
- * @dentry: dentry to drop
- *
- * d_drop() unhashes the entry from the parent dentry hashes, so that it won't
- * be found through a VFS lookup any more. Note that this is different from
- * deleting the dentry - d_delete will try to mark the dentry negative if
- * possible, giving a successful _negative_ lookup, while d_drop will
- * just make the cache lookup fail.
- *
- * d_drop() is used mainly for stuff that wants to invalidate a dentry for some
- * reason (NFS timeouts or autofs deletes).
- *
- * __d_drop requires dentry->d_lock
- * ___d_drop doesn't mark dentry as "unhashed"
- *   (dentry->d_hash.pprev will be LIST_POISON2, not NULL).
- */
 static void ___d_drop(struct dentry *dentry)
 {
 	struct hlist_bl_head *b;
 	/*
 	 * Hashed dentries are normally on the dentry hashtable,
 	 * with the exception of those newly allocated by
 	 * d_obtain_root, which are always IS_ROOT:
 	 */
 	if (unlikely(IS_ROOT(dentry)))
 		b = &dentry->d_sb->s_roots;
 	else
 		b = d_hash(dentry->d_name.hash);
 
 	hlist_bl_lock(b);
 	__hlist_bl_del(&dentry->d_hash);
 	hlist_bl_unlock(b);
 }
 
 void __d_drop(struct dentry *dentry)
 {
 	if (!d_unhashed(dentry)) {
 		___d_drop(dentry);
 		dentry->d_hash.pprev = NULL;
 		write_seqcount_invalidate(&dentry->d_seq);
 	}
 }
 EXPORT_SYMBOL(__d_drop);
 
+/**
+ * d_drop - drop a dentry
+ * @dentry: dentry to drop
+ *
+ * d_drop() unhashes the entry from the parent dentry hashes, so that it won't
+ * be found through a VFS lookup any more. Note that this is different from
+ * deleting the dentry - d_delete will try to mark the dentry negative if
+ * possible, giving a successful _negative_ lookup, while d_drop will
+ * just make the cache lookup fail.
+ *
+ * d_drop() is used mainly for stuff that wants to invalidate a dentry for some
+ * reason (NFS timeouts or autofs deletes).
+ *
+ * __d_drop requires dentry->d_lock
+ * ___d_drop doesn't mark dentry as "unhashed"
+ *   (dentry->d_hash.pprev will be LIST_POISON2, not NULL).
+ */
 void d_drop(struct dentry *dentry)
 {
 	spin_lock(&dentry->d_lock);
 	__d_drop(dentry);
 	spin_unlock(&dentry->d_lock);
 }
 EXPORT_SYMBOL(d_drop);
 
 static inline void dentry_unlist(struct dentry *dentry, struct dentry *parent)
 {
 	struct dentry *next;
 	/*
 	 * Inform d_walk() and shrink_dentry_list() that we are no longer
 	 * attached to the dentry tree
 	 */
 	dentry->d_flags |= DCACHE_DENTRY_KILLED;
 	if (unlikely(list_empty(&dentry->d_child)))
 		return;
 	__list_del_entry(&dentry->d_child);
 	/*
@@ -972,73 +972,73 @@ static struct dentry * __d_find_any_alias(struct inode *inode)
 }
 
 /**
  * d_find_any_alias - find any alias for a given inode
  * @inode: inode to find an alias for
  *
  * If any aliases exist for the given inode, take and return a
  * reference for one of them.  If no aliases exist, return %NULL.
  */
 struct dentry *d_find_any_alias(struct inode *inode)
 {
 	struct dentry *de;
 
 	spin_lock(&inode->i_lock);
 	de = __d_find_any_alias(inode);
 	spin_unlock(&inode->i_lock);
 	return de;
 }
 EXPORT_SYMBOL(d_find_any_alias);
 
+static struct dentry *__d_find_alias(struct inode *inode)
+{
+	struct dentry *alias;
+
+	if (S_ISDIR(inode->i_mode))
+		return __d_find_any_alias(inode);
+
+	hlist_for_each_entry(alias, &inode->i_dentry, d_u.d_alias) {
+		spin_lock(&alias->d_lock);
+ 		if (!d_unhashed(alias)) {
+			__dget_dlock(alias);
+			spin_unlock(&alias->d_lock);
+			return alias;
+		}
+		spin_unlock(&alias->d_lock);
+	}
+	return NULL;
+}
+
 /**
  * d_find_alias - grab a hashed alias of inode
  * @inode: inode in question
  *
  * If inode has a hashed alias, or is a directory and has any alias,
  * acquire the reference to alias and return it. Otherwise return NULL.
  * Notice that if inode is a directory there can be only one alias and
  * it can be unhashed only if it has no children, or if it is the root
  * of a filesystem, or if the directory was renamed and d_revalidate
  * was the first vfs operation to notice.
  *
  * If the inode has an IS_ROOT, DCACHE_DISCONNECTED alias, then prefer
  * any other hashed alias over that one.
  */
-static struct dentry *__d_find_alias(struct inode *inode)
-{
-	struct dentry *alias;
-
-	if (S_ISDIR(inode->i_mode))
-		return __d_find_any_alias(inode);
-
-	hlist_for_each_entry(alias, &inode->i_dentry, d_u.d_alias) {
-		spin_lock(&alias->d_lock);
- 		if (!d_unhashed(alias)) {
-			__dget_dlock(alias);
-			spin_unlock(&alias->d_lock);
-			return alias;
-		}
-		spin_unlock(&alias->d_lock);
-	}
-	return NULL;
-}
-
 struct dentry *d_find_alias(struct inode *inode)
 {
 	struct dentry *de = NULL;
 
 	if (!hlist_empty(&inode->i_dentry)) {
 		spin_lock(&inode->i_lock);
 		de = __d_find_alias(inode);
 		spin_unlock(&inode->i_lock);
 	}
 	return de;
 }
 EXPORT_SYMBOL(d_find_alias);
 
 /*
  *	Try to kill dentries associated with this inode.
  * WARNING: you must own a reference to inode.
  */
 void d_prune_aliases(struct inode *inode)
 {
 	struct dentry *dentry;
diff --git a/fs/inode.c b/fs/inode.c
index 9d78c37b00b8..aad3dcf2e259 100644
--- a/fs/inode.c
+++ b/fs/inode.c
@@ -1479,41 +1479,41 @@ EXPORT_SYMBOL(find_inode_nowait);
 struct inode *find_inode_rcu(struct super_block *sb, unsigned long hashval,
 			     int (*test)(struct inode *, void *), void *data)
 {
 	struct hlist_head *head = inode_hashtable + hash(sb, hashval);
 	struct inode *inode;
 
 	RCU_LOCKDEP_WARN(!rcu_read_lock_held(),
 			 "suspicious find_inode_rcu() usage");
 
 	hlist_for_each_entry_rcu(inode, head, i_hash) {
 		if (inode->i_sb == sb &&
 		    !(READ_ONCE(inode->i_state) & (I_FREEING | I_WILL_FREE)) &&
 		    test(inode, data))
 			return inode;
 	}
 	return NULL;
 }
 EXPORT_SYMBOL(find_inode_rcu);
 
 /**
- * find_inode_by_rcu - Find an inode in the inode cache
+ * find_inode_by_ino_rcu - Find an inode in the inode cache
  * @sb:		Super block of file system to search
  * @ino:	The inode number to match
  *
  * Search for the inode specified by @hashval and @data in the inode cache,
  * where the helper function @test will return 0 if the inode does not match
  * and 1 if it does.  The @test function must be responsible for taking the
  * i_lock spin_lock and checking i_state for an inode being freed or being
  * initialized.
  *
  * If successful, this will return the inode for which the @test function
  * returned 1 and NULL otherwise.
  *
  * The @test function is not permitted to take a ref on any inode presented.
  * It is also not permitted to sleep.
  *
  * The caller must hold the RCU read lock.
  */
 struct inode *find_inode_by_ino_rcu(struct super_block *sb,
 				    unsigned long ino)
 {
@@ -1761,41 +1761,41 @@ int generic_update_time(struct inode *inode, struct timespec64 *time, int flags)
 
 	if (dirty)
 		iflags |= I_DIRTY_SYNC;
 	__mark_inode_dirty(inode, iflags);
 	return 0;
 }
 EXPORT_SYMBOL(generic_update_time);
 
 /*
  * This does the actual work of updating an inodes time or version.  Must have
  * had called mnt_want_write() before calling this.
  */
 static int update_time(struct inode *inode, struct timespec64 *time, int flags)
 {
 	if (inode->i_op->update_time)
 		return inode->i_op->update_time(inode, time, flags);
 	return generic_update_time(inode, time, flags);
 }
 
 /**
- *	touch_atime	-	update the access time
+ *	atime_needs_update	-	update the access time
  *	@path: the &struct path to update
  *	@inode: inode to update
  *
  *	Update the accessed time on an inode and mark it for writeback.
  *	This function automatically handles read only file systems and media,
  *	as well as the "noatime" flag and inode specific "noatime" markers.
  */
 bool atime_needs_update(const struct path *path, struct inode *inode)
 {
 	struct vfsmount *mnt = path->mnt;
 	struct timespec64 now;
 
 	if (inode->i_flags & S_NOATIME)
 		return false;
 
 	/* Atime updates will likely cause i_uid and i_gid to be written
 	 * back improprely if their true value is unknown to the vfs.
 	 */
 	if (HAS_UNMAPPED_ID(inode))
 		return false;
diff --git a/fs/seq_file.c b/fs/seq_file.c
index 07b33c1f34a9..7e16eaea999b 100644
--- a/fs/seq_file.c
+++ b/fs/seq_file.c
@@ -647,41 +647,42 @@ void seq_putc(struct seq_file *m, char c)
 		return;
 
 	m->buf[m->count++] = c;
 }
 EXPORT_SYMBOL(seq_putc);
 
 void seq_puts(struct seq_file *m, const char *s)
 {
 	int len = strlen(s);
 
 	if (m->count + len >= m->size) {
 		seq_set_overflow(m);
 		return;
 	}
 	memcpy(m->buf + m->count, s, len);
 	m->count += len;
 }
 EXPORT_SYMBOL(seq_puts);
 
 /**
- * A helper routine for putting decimal numbers without rich format of printf().
+ * seq_put_decimal_ull_width - A helper routine for putting decimal numbers
+ * 			       without rich format of printf().
  * only 'unsigned long long' is supported.
  * @m: seq_file identifying the buffer to which data should be written
  * @delimiter: a string which is printed before the number
  * @num: the number
  * @width: a minimum field width
  *
  * This routine will put strlen(delimiter) + number into seq_filed.
  * This routine is very quick when you show lots of numbers.
  * In usual cases, it will be better to use seq_printf(). It's easier to read.
  */
 void seq_put_decimal_ull_width(struct seq_file *m, const char *delimiter,
 			 unsigned long long num, unsigned int width)
 {
 	int len;
 
 	if (m->count + 2 >= m->size) /* we'll write 2 bytes at least */
 		goto overflow;
 
 	if (delimiter && delimiter[0]) {
 		if (delimiter[1] == 0)
@@ -1022,41 +1023,41 @@ EXPORT_SYMBOL(seq_hlist_start_head_rcu);
  *
  * This list-traversal primitive may safely run concurrently with
  * the _rcu list-mutation primitives such as hlist_add_head_rcu()
  * as long as the traversal is guarded by rcu_read_lock().
  */
 struct hlist_node *seq_hlist_next_rcu(void *v,
 				      struct hlist_head *head,
 				      loff_t *ppos)
 {
 	struct hlist_node *node = v;
 
 	++*ppos;
 	if (v == SEQ_START_TOKEN)
 		return rcu_dereference(head->first);
 	else
 		return rcu_dereference(node->next);
 }
 EXPORT_SYMBOL(seq_hlist_next_rcu);
 
 /**
- * seq_hlist_start_precpu - start an iteration of a percpu hlist array
+ * seq_hlist_start_percpu - start an iteration of a percpu hlist array
  * @head: pointer to percpu array of struct hlist_heads
  * @cpu:  pointer to cpu "cursor"
  * @pos:  start position of sequence
  *
  * Called at seq_file->op->start().
  */
 struct hlist_node *
 seq_hlist_start_percpu(struct hlist_head __percpu *head, int *cpu, loff_t pos)
 {
 	struct hlist_node *node;
 
 	for_each_possible_cpu(*cpu) {
 		hlist_for_each(node, per_cpu_ptr(head, *cpu)) {
 			if (pos-- == 0)
 				return node;
 		}
 	}
 	return NULL;
 }
 EXPORT_SYMBOL(seq_hlist_start_percpu);
diff --git a/fs/super.c b/fs/super.c
index 98bb0629ee10..912636bbda9e 100644
--- a/fs/super.c
+++ b/fs/super.c
@@ -1754,67 +1754,67 @@ int freeze_super(struct super_block *sb)
 			printk(KERN_ERR
 				"VFS:Filesystem freeze failed\n");
 			sb->s_writers.frozen = SB_UNFROZEN;
 			sb_freeze_unlock(sb);
 			wake_up(&sb->s_writers.wait_unfrozen);
 			deactivate_locked_super(sb);
 			return ret;
 		}
 	}
 	/*
 	 * For debugging purposes so that fs can warn if it sees write activity
 	 * when frozen is set to SB_FREEZE_COMPLETE, and for thaw_super().
 	 */
 	sb->s_writers.frozen = SB_FREEZE_COMPLETE;
 	lockdep_sb_freeze_release(sb);
 	up_write(&sb->s_umount);
 	return 0;
 }
 EXPORT_SYMBOL(freeze_super);
 
-/**
- * thaw_super -- unlock filesystem
- * @sb: the super to thaw
- *
- * Unlocks the filesystem and marks it writeable again after freeze_super().
- */
 static int thaw_super_locked(struct super_block *sb)
 {
 	int error;
 
 	if (sb->s_writers.frozen != SB_FREEZE_COMPLETE) {
 		up_write(&sb->s_umount);
 		return -EINVAL;
 	}
 
 	if (sb_rdonly(sb)) {
 		sb->s_writers.frozen = SB_UNFROZEN;
 		goto out;
 	}
 
 	lockdep_sb_freeze_acquire(sb);
 
 	if (sb->s_op->unfreeze_fs) {
 		error = sb->s_op->unfreeze_fs(sb);
 		if (error) {
 			printk(KERN_ERR
 				"VFS:Filesystem thaw failed\n");
 			lockdep_sb_freeze_release(sb);
 			up_write(&sb->s_umount);
 			return error;
 		}
 	}
 
 	sb->s_writers.frozen = SB_UNFROZEN;
 	sb_freeze_unlock(sb);
 out:
 	wake_up(&sb->s_writers.wait_unfrozen);
 	deactivate_locked_super(sb);
 	return 0;
 }
 
+/**
+ * thaw_super -- unlock filesystem
+ * @sb: the super to thaw
+ *
+ * Unlocks the filesystem and marks it writeable again after freeze_super().
+ */
 int thaw_super(struct super_block *sb)
 {
 	down_write(&sb->s_umount);
 	return thaw_super_locked(sb);
 }
 EXPORT_SYMBOL(thaw_super);
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 12/27] jbd2: fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (10 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 11/27] fs: fix " Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-20  3:38   ` Theodore Y. Ts'o
  2020-11-16 10:18 ` [PATCH v4 13/27] pstore/zone: fix a kernel-doc markup Mauro Carvalho Chehab
                   ` (15 subsequent siblings)
  27 siblings, 1 reply; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Theodore Ts'o, Jan Kara
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-ext4, linux-kernel, Jan Kara

Kernel-doc markup should use this format:
        identifier - description

They should not have any type before that, as otherwise
the parser won't do the right thing.

Also, some identifiers have different names between their
prototypes and the kernel-doc markup.

Reviewed-by: Jan Kara <jack@suse.cz>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 fs/jbd2/journal.c     | 34 ++++++++++++++++++----------------
 fs/jbd2/transaction.c | 31 ++++++++++++++++---------------
 include/linux/jbd2.h  |  2 +-
 3 files changed, 35 insertions(+), 32 deletions(-)

diff --git a/fs/jbd2/journal.c b/fs/jbd2/journal.c
index 0c3d5e3b24b2..188f79d76988 100644
--- a/fs/jbd2/journal.c
+++ b/fs/jbd2/journal.c
@@ -549,57 +549,59 @@ static int __jbd2_journal_force_commit(journal_t *journal)
 	} else if (journal->j_committing_transaction)
 		transaction = journal->j_committing_transaction;
 
 	if (!transaction) {
 		/* Nothing to commit */
 		read_unlock(&journal->j_state_lock);
 		return 0;
 	}
 	tid = transaction->t_tid;
 	read_unlock(&journal->j_state_lock);
 	if (need_to_start)
 		jbd2_log_start_commit(journal, tid);
 	ret = jbd2_log_wait_commit(journal, tid);
 	if (!ret)
 		ret = 1;
 
 	return ret;
 }
 
 /**
- * Force and wait upon a commit if the calling process is not within
- * transaction.  This is used for forcing out undo-protected data which contains
- * bitmaps, when the fs is running out of space.
+ * jbd2_journal_force_commit_nested - Force and wait upon a commit if the
+ * calling process is not within transaction.
  *
  * @journal: journal to force
  * Returns true if progress was made.
+ *
+ * This is used for forcing out undo-protected data which contains
+ * bitmaps, when the fs is running out of space.
  */
 int jbd2_journal_force_commit_nested(journal_t *journal)
 {
 	int ret;
 
 	ret = __jbd2_journal_force_commit(journal);
 	return ret > 0;
 }
 
 /**
- * int journal_force_commit() - force any uncommitted transactions
+ * jbd2_journal_force_commit() - force any uncommitted transactions
  * @journal: journal to force
  *
  * Caller want unconditional commit. We can only force the running transaction
  * if we don't have an active handle, otherwise, we will deadlock.
  */
 int jbd2_journal_force_commit(journal_t *journal)
 {
 	int ret;
 
 	J_ASSERT(!current->journal_info);
 	ret = __jbd2_journal_force_commit(journal);
 	if (ret > 0)
 		ret = 0;
 	return ret;
 }
 
 /*
  * Start a commit of the current running transaction (if any).  Returns true
  * if a transaction is going to be committed (or is currently already
  * committing), and fills its tid in at *ptid
@@ -1864,41 +1866,41 @@ static int load_superblock(journal_t *journal)
 	journal->j_first = be32_to_cpu(sb->s_first);
 	journal->j_errno = be32_to_cpu(sb->s_errno);
 	journal->j_last = be32_to_cpu(sb->s_maxlen);
 
 	if (jbd2_has_feature_fast_commit(journal)) {
 		journal->j_fc_last = be32_to_cpu(sb->s_maxlen);
 		num_fc_blocks = be32_to_cpu(sb->s_num_fc_blks);
 		if (!num_fc_blocks)
 			num_fc_blocks = JBD2_MIN_FC_BLOCKS;
 		if (journal->j_last - num_fc_blocks >= JBD2_MIN_JOURNAL_BLOCKS)
 			journal->j_last = journal->j_fc_last - num_fc_blocks;
 		journal->j_fc_first = journal->j_last + 1;
 		journal->j_fc_off = 0;
 	}
 
 	return 0;
 }
 
 
 /**
- * int jbd2_journal_load() - Read journal from disk.
+ * jbd2_journal_load() - Read journal from disk.
  * @journal: Journal to act on.
  *
  * Given a journal_t structure which tells us which disk blocks contain
  * a journal, read the journal from disk to initialise the in-memory
  * structures.
  */
 int jbd2_journal_load(journal_t *journal)
 {
 	int err;
 	journal_superblock_t *sb;
 
 	err = load_superblock(journal);
 	if (err)
 		return err;
 
 	sb = journal->j_superblock;
 	/* If this is a V2 superblock, then we have to check the
 	 * features flags on it. */
 
 	if (journal->j_format_version >= 2) {
@@ -1934,41 +1936,41 @@ int jbd2_journal_load(journal_t *journal)
 	 * clear JBD2_ABORT flag initialized in journal_init_common
 	 * here to update log tail information with the newest seq.
 	 */
 	journal->j_flags &= ~JBD2_ABORT;
 
 	/* OK, we've finished with the dynamic journal bits:
 	 * reinitialise the dynamic contents of the superblock in memory
 	 * and reset them on disk. */
 	if (journal_reset(journal))
 		goto recovery_error;
 
 	journal->j_flags |= JBD2_LOADED;
 	return 0;
 
 recovery_error:
 	printk(KERN_WARNING "JBD2: recovery failed\n");
 	return -EIO;
 }
 
 /**
- * void jbd2_journal_destroy() - Release a journal_t structure.
+ * jbd2_journal_destroy() - Release a journal_t structure.
  * @journal: Journal to act on.
  *
  * Release a journal_t structure once it is no longer in use by the
  * journaled object.
  * Return <0 if we couldn't clean up the journal.
  */
 int jbd2_journal_destroy(journal_t *journal)
 {
 	int err = 0;
 
 	/* Wait for the commit thread to wake up and die. */
 	journal_kill_thread(journal);
 
 	/* Force a final log commit */
 	if (journal->j_running_transaction)
 		jbd2_journal_commit_transaction(journal);
 
 	/* Force any old transactions to disk */
 
 	/* Totally anal locking here... */
@@ -2011,76 +2013,76 @@ int jbd2_journal_destroy(journal_t *journal)
 			err = -EIO;
 		brelse(journal->j_sb_buffer);
 	}
 
 	if (journal->j_proc_entry)
 		jbd2_stats_proc_exit(journal);
 	iput(journal->j_inode);
 	if (journal->j_revoke)
 		jbd2_journal_destroy_revoke(journal);
 	if (journal->j_chksum_driver)
 		crypto_free_shash(journal->j_chksum_driver);
 	kfree(journal->j_fc_wbuf);
 	kfree(journal->j_wbuf);
 	kfree(journal);
 
 	return err;
 }
 
 
 /**
- *int jbd2_journal_check_used_features() - Check if features specified are used.
+ * jbd2_journal_check_used_features() - Check if features specified are used.
  * @journal: Journal to check.
  * @compat: bitmask of compatible features
  * @ro: bitmask of features that force read-only mount
  * @incompat: bitmask of incompatible features
  *
  * Check whether the journal uses all of a given set of
  * features.  Return true (non-zero) if it does.
  **/
 
 int jbd2_journal_check_used_features(journal_t *journal, unsigned long compat,
 				 unsigned long ro, unsigned long incompat)
 {
 	journal_superblock_t *sb;
 
 	if (!compat && !ro && !incompat)
 		return 1;
 	/* Load journal superblock if it is not loaded yet. */
 	if (journal->j_format_version == 0 &&
 	    journal_get_superblock(journal) != 0)
 		return 0;
 	if (journal->j_format_version == 1)
 		return 0;
 
 	sb = journal->j_superblock;
 
 	if (((be32_to_cpu(sb->s_feature_compat) & compat) == compat) &&
 	    ((be32_to_cpu(sb->s_feature_ro_compat) & ro) == ro) &&
 	    ((be32_to_cpu(sb->s_feature_incompat) & incompat) == incompat))
 		return 1;
 
 	return 0;
 }
 
 /**
- * int jbd2_journal_check_available_features() - Check feature set in journalling layer
+ * jbd2_journal_check_available_features() - Check feature set in journalling layer
  * @journal: Journal to check.
  * @compat: bitmask of compatible features
  * @ro: bitmask of features that force read-only mount
  * @incompat: bitmask of incompatible features
  *
  * Check whether the journaling code supports the use of
  * all of a given set of features on this journal.  Return true
  * (non-zero) if it can. */
 
 int jbd2_journal_check_available_features(journal_t *journal, unsigned long compat,
 				      unsigned long ro, unsigned long incompat)
 {
 	if (!compat && !ro && !incompat)
 		return 1;
 
 	/* We can support any known requested features iff the
 	 * superblock is in version 2.  Otherwise we fail to support any
 	 * extended sb features. */
 
 	if (journal->j_format_version != 2)
@@ -2109,41 +2111,41 @@ jbd2_journal_initialize_fast_commit(journal_t *journal)
 	/* Are we called twice? */
 	WARN_ON(journal->j_fc_wbuf != NULL);
 	journal->j_fc_wbuf = kmalloc_array(num_fc_blks,
 				sizeof(struct buffer_head *), GFP_KERNEL);
 	if (!journal->j_fc_wbuf)
 		return -ENOMEM;
 
 	journal->j_fc_wbufsize = num_fc_blks;
 	journal->j_fc_last = journal->j_last;
 	journal->j_last = journal->j_fc_last - num_fc_blks;
 	journal->j_fc_first = journal->j_last + 1;
 	journal->j_fc_off = 0;
 	journal->j_free = journal->j_last - journal->j_first;
 	journal->j_max_transaction_buffers =
 		jbd2_journal_get_max_txn_bufs(journal);
 
 	return 0;
 }
 
 /**
- * int jbd2_journal_set_features() - Mark a given journal feature in the superblock
+ * jbd2_journal_set_features() - Mark a given journal feature in the superblock
  * @journal: Journal to act on.
  * @compat: bitmask of compatible features
  * @ro: bitmask of features that force read-only mount
  * @incompat: bitmask of incompatible features
  *
  * Mark a given journal feature as present on the
  * superblock.  Returns true if the requested features could be set.
  *
  */
 
 int jbd2_journal_set_features(journal_t *journal, unsigned long compat,
 			  unsigned long ro, unsigned long incompat)
 {
 #define INCOMPAT_FEATURE_ON(f) \
 		((incompat & (f)) && !(sb->s_feature_incompat & cpu_to_be32(f)))
 #define COMPAT_FEATURE_ON(f) \
 		((compat & (f)) && !(sb->s_feature_compat & cpu_to_be32(f)))
 	journal_superblock_t *sb;
 
 	if (jbd2_journal_check_used_features(journal, compat, ro, incompat))
@@ -2200,70 +2202,70 @@ int jbd2_journal_set_features(journal_t *journal, unsigned long compat,
 
 	/* If enabling v1 checksums, downgrade superblock */
 	if (COMPAT_FEATURE_ON(JBD2_FEATURE_COMPAT_CHECKSUM))
 		sb->s_feature_incompat &=
 			~cpu_to_be32(JBD2_FEATURE_INCOMPAT_CSUM_V2 |
 				     JBD2_FEATURE_INCOMPAT_CSUM_V3);
 
 	sb->s_feature_compat    |= cpu_to_be32(compat);
 	sb->s_feature_ro_compat |= cpu_to_be32(ro);
 	sb->s_feature_incompat  |= cpu_to_be32(incompat);
 	unlock_buffer(journal->j_sb_buffer);
 	journal->j_revoke_records_per_block =
 				journal_revoke_records_per_block(journal);
 
 	return 1;
 #undef COMPAT_FEATURE_ON
 #undef INCOMPAT_FEATURE_ON
 }
 
 /*
- * jbd2_journal_clear_features () - Clear a given journal feature in the
+ * jbd2_journal_clear_features() - Clear a given journal feature in the
  * 				    superblock
  * @journal: Journal to act on.
  * @compat: bitmask of compatible features
  * @ro: bitmask of features that force read-only mount
  * @incompat: bitmask of incompatible features
  *
  * Clear a given journal feature as present on the
  * superblock.
  */
 void jbd2_journal_clear_features(journal_t *journal, unsigned long compat,
 				unsigned long ro, unsigned long incompat)
 {
 	journal_superblock_t *sb;
 
 	jbd_debug(1, "Clear features 0x%lx/0x%lx/0x%lx\n",
 		  compat, ro, incompat);
 
 	sb = journal->j_superblock;
 
 	sb->s_feature_compat    &= ~cpu_to_be32(compat);
 	sb->s_feature_ro_compat &= ~cpu_to_be32(ro);
 	sb->s_feature_incompat  &= ~cpu_to_be32(incompat);
 	journal->j_revoke_records_per_block =
 				journal_revoke_records_per_block(journal);
 }
 EXPORT_SYMBOL(jbd2_journal_clear_features);
 
 /**
- * int jbd2_journal_flush () - Flush journal
+ * jbd2_journal_flush() - Flush journal
  * @journal: Journal to act on.
  *
  * Flush all data for a given journal to disk and empty the journal.
  * Filesystems can use this when remounting readonly to ensure that
  * recovery does not need to happen on remount.
  */
 
 int jbd2_journal_flush(journal_t *journal)
 {
 	int err = 0;
 	transaction_t *transaction = NULL;
 
 	write_lock(&journal->j_state_lock);
 
 	/* Force everything buffered to the log... */
 	if (journal->j_running_transaction) {
 		transaction = journal->j_running_transaction;
 		__jbd2_log_start_commit(journal, transaction->t_tid);
 	} else if (journal->j_committing_transaction)
 		transaction = journal->j_committing_transaction;
@@ -2304,82 +2306,82 @@ int jbd2_journal_flush(journal_t *journal)
 
 	/* Finally, mark the journal as really needing no recovery.
 	 * This sets s_start==0 in the underlying superblock, which is
 	 * the magic code for a fully-recovered superblock.  Any future
 	 * commits of data to the journal will restore the current
 	 * s_start value. */
 	jbd2_mark_journal_empty(journal, REQ_SYNC | REQ_FUA);
 	mutex_unlock(&journal->j_checkpoint_mutex);
 	write_lock(&journal->j_state_lock);
 	J_ASSERT(!journal->j_running_transaction);
 	J_ASSERT(!journal->j_committing_transaction);
 	J_ASSERT(!journal->j_checkpoint_transactions);
 	J_ASSERT(journal->j_head == journal->j_tail);
 	J_ASSERT(journal->j_tail_sequence == journal->j_transaction_sequence);
 	write_unlock(&journal->j_state_lock);
 out:
 	return err;
 }
 
 /**
- * int jbd2_journal_wipe() - Wipe journal contents
+ * jbd2_journal_wipe() - Wipe journal contents
  * @journal: Journal to act on.
  * @write: flag (see below)
  *
  * Wipe out all of the contents of a journal, safely.  This will produce
  * a warning if the journal contains any valid recovery information.
  * Must be called between journal_init_*() and jbd2_journal_load().
  *
  * If 'write' is non-zero, then we wipe out the journal on disk; otherwise
  * we merely suppress recovery.
  */
 
 int jbd2_journal_wipe(journal_t *journal, int write)
 {
 	int err = 0;
 
 	J_ASSERT (!(journal->j_flags & JBD2_LOADED));
 
 	err = load_superblock(journal);
 	if (err)
 		return err;
 
 	if (!journal->j_tail)
 		goto no_recovery;
 
 	printk(KERN_WARNING "JBD2: %s recovery information on journal\n",
 		write ? "Clearing" : "Ignoring");
 
 	err = jbd2_journal_skip_recovery(journal);
 	if (write) {
 		/* Lock to make assertions happy... */
 		mutex_lock_io(&journal->j_checkpoint_mutex);
 		jbd2_mark_journal_empty(journal, REQ_SYNC | REQ_FUA);
 		mutex_unlock(&journal->j_checkpoint_mutex);
 	}
 
  no_recovery:
 	return err;
 }
 
 /**
- * void jbd2_journal_abort () - Shutdown the journal immediately.
+ * jbd2_journal_abort () - Shutdown the journal immediately.
  * @journal: the journal to shutdown.
  * @errno:   an error number to record in the journal indicating
  *           the reason for the shutdown.
  *
  * Perform a complete, immediate shutdown of the ENTIRE
  * journal (not of a single transaction).  This operation cannot be
  * undone without closing and reopening the journal.
  *
  * The jbd2_journal_abort function is intended to support higher level error
  * recovery mechanisms such as the ext2/ext3 remount-readonly error
  * mode.
  *
  * Journal abort has very specific semantics.  Any existing dirty,
  * unjournaled buffers in the main filesystem will still be written to
  * disk by bdflush, but the journaling mechanism will be suspended
  * immediately and no further transaction commits will be honoured.
  *
  * Any dirty, journaled buffers will be written back to disk without
  * hitting the journal.  Atomicity cannot be guaranteed on an aborted
  * filesystem, but we _do_ attempt to leave as much data as possible
@@ -2436,85 +2438,85 @@ void jbd2_journal_abort(journal_t *journal, int errno)
 	 * to release all journaled buffer.
 	 */
 	pr_err("Aborting journal on device %s.\n", journal->j_devname);
 
 	journal->j_flags |= JBD2_ABORT;
 	journal->j_errno = errno;
 	transaction = journal->j_running_transaction;
 	if (transaction)
 		__jbd2_log_start_commit(journal, transaction->t_tid);
 	write_unlock(&journal->j_state_lock);
 
 	/*
 	 * Record errno to the journal super block, so that fsck and jbd2
 	 * layer could realise that a filesystem check is needed.
 	 */
 	jbd2_journal_update_sb_errno(journal);
 	mutex_unlock(&journal->j_abort_mutex);
 }
 
 /**
- * int jbd2_journal_errno () - returns the journal's error state.
+ * jbd2_journal_errno() - returns the journal's error state.
  * @journal: journal to examine.
  *
  * This is the errno number set with jbd2_journal_abort(), the last
  * time the journal was mounted - if the journal was stopped
  * without calling abort this will be 0.
  *
  * If the journal has been aborted on this mount time -EROFS will
  * be returned.
  */
 int jbd2_journal_errno(journal_t *journal)
 {
 	int err;
 
 	read_lock(&journal->j_state_lock);
 	if (journal->j_flags & JBD2_ABORT)
 		err = -EROFS;
 	else
 		err = journal->j_errno;
 	read_unlock(&journal->j_state_lock);
 	return err;
 }
 
 /**
- * int jbd2_journal_clear_err () - clears the journal's error state
+ * jbd2_journal_clear_err() - clears the journal's error state
  * @journal: journal to act on.
  *
  * An error must be cleared or acked to take a FS out of readonly
  * mode.
  */
 int jbd2_journal_clear_err(journal_t *journal)
 {
 	int err = 0;
 
 	write_lock(&journal->j_state_lock);
 	if (journal->j_flags & JBD2_ABORT)
 		err = -EROFS;
 	else
 		journal->j_errno = 0;
 	write_unlock(&journal->j_state_lock);
 	return err;
 }
 
 /**
- * void jbd2_journal_ack_err() - Ack journal err.
+ * jbd2_journal_ack_err() - Ack journal err.
  * @journal: journal to act on.
  *
  * An error must be cleared or acked to take a FS out of readonly
  * mode.
  */
 void jbd2_journal_ack_err(journal_t *journal)
 {
 	write_lock(&journal->j_state_lock);
 	if (journal->j_errno)
 		journal->j_flags |= JBD2_ACK_ERR;
 	write_unlock(&journal->j_state_lock);
 }
 
 int jbd2_journal_blocks_per_page(struct inode *inode)
 {
 	return 1 << (PAGE_SHIFT - inode->i_sb->s_blocksize_bits);
 }
 
 /*
  * helper functions to deal with 32 or 64bit block numbers.
diff --git a/fs/jbd2/transaction.c b/fs/jbd2/transaction.c
index d54f04674e8e..9396666b7314 100644
--- a/fs/jbd2/transaction.c
+++ b/fs/jbd2/transaction.c
@@ -502,41 +502,41 @@ handle_t *jbd2__journal_start(journal_t *journal, int nblocks, int rsv_blocks,
 
 	err = start_this_handle(journal, handle, gfp_mask);
 	if (err < 0) {
 		if (handle->h_rsv_handle)
 			jbd2_free_handle(handle->h_rsv_handle);
 		jbd2_free_handle(handle);
 		return ERR_PTR(err);
 	}
 	handle->h_type = type;
 	handle->h_line_no = line_no;
 	trace_jbd2_handle_start(journal->j_fs_dev->bd_dev,
 				handle->h_transaction->t_tid, type,
 				line_no, nblocks);
 
 	return handle;
 }
 EXPORT_SYMBOL(jbd2__journal_start);
 
 
 /**
- * handle_t *jbd2_journal_start() - Obtain a new handle.
+ * jbd2_journal_start() - Obtain a new handle.
  * @journal: Journal to start transaction on.
  * @nblocks: number of block buffer we might modify
  *
  * We make sure that the transaction can guarantee at least nblocks of
  * modified buffers in the log.  We block until the log can guarantee
  * that much space. Additionally, if rsv_blocks > 0, we also create another
  * handle with rsv_blocks reserved blocks in the journal. This handle is
  * stored in h_rsv_handle. It is not attached to any particular transaction
  * and thus doesn't block transaction commit. If the caller uses this reserved
  * handle, it has to set h_rsv_handle to NULL as otherwise jbd2_journal_stop()
  * on the parent handle will dispose the reserved one. Reserved handle has to
  * be converted to a normal handle using jbd2_journal_start_reserved() before
  * it can be used.
  *
  * Return a pointer to a newly allocated handle, or an ERR_PTR() value
  * on failure.
  */
 handle_t *jbd2_journal_start(journal_t *journal, int nblocks)
 {
 	return jbd2__journal_start(journal, nblocks, 0, 0, GFP_NOFS, 0, 0);
@@ -549,41 +549,41 @@ static void __jbd2_journal_unreserve_handle(handle_t *handle, transaction_t *t)
 
 	WARN_ON(!handle->h_reserved);
 	sub_reserved_credits(journal, handle->h_total_credits);
 	if (t)
 		atomic_sub(handle->h_total_credits, &t->t_outstanding_credits);
 }
 
 void jbd2_journal_free_reserved(handle_t *handle)
 {
 	journal_t *journal = handle->h_journal;
 
 	/* Get j_state_lock to pin running transaction if it exists */
 	read_lock(&journal->j_state_lock);
 	__jbd2_journal_unreserve_handle(handle, journal->j_running_transaction);
 	read_unlock(&journal->j_state_lock);
 	jbd2_free_handle(handle);
 }
 EXPORT_SYMBOL(jbd2_journal_free_reserved);
 
 /**
- * int jbd2_journal_start_reserved() - start reserved handle
+ * jbd2_journal_start_reserved() - start reserved handle
  * @handle: handle to start
  * @type: for handle statistics
  * @line_no: for handle statistics
  *
  * Start handle that has been previously reserved with jbd2_journal_reserve().
  * This attaches @handle to the running transaction (or creates one if there's
  * not transaction running). Unlike jbd2_journal_start() this function cannot
  * block on journal commit, checkpointing, or similar stuff. It can block on
  * memory allocation or frozen journal though.
  *
  * Return 0 on success, non-zero on error - handle is freed in that case.
  */
 int jbd2_journal_start_reserved(handle_t *handle, unsigned int type,
 				unsigned int line_no)
 {
 	journal_t *journal = handle->h_journal;
 	int ret = -EIO;
 
 	if (WARN_ON(!handle->h_reserved)) {
 		/* Someone passed in normal handle? Just stop it. */
@@ -603,41 +603,41 @@ int jbd2_journal_start_reserved(handle_t *handle, unsigned int type,
 	/*
 	 * GFP_NOFS is here because callers are likely from writeback or
 	 * similarly constrained call sites
 	 */
 	ret = start_this_handle(journal, handle, GFP_NOFS);
 	if (ret < 0) {
 		handle->h_journal = journal;
 		jbd2_journal_free_reserved(handle);
 		return ret;
 	}
 	handle->h_type = type;
 	handle->h_line_no = line_no;
 	trace_jbd2_handle_start(journal->j_fs_dev->bd_dev,
 				handle->h_transaction->t_tid, type,
 				line_no, handle->h_total_credits);
 	return 0;
 }
 EXPORT_SYMBOL(jbd2_journal_start_reserved);
 
 /**
- * int jbd2_journal_extend() - extend buffer credits.
+ * jbd2_journal_extend() - extend buffer credits.
  * @handle:  handle to 'extend'
  * @nblocks: nr blocks to try to extend by.
  * @revoke_records: number of revoke records to try to extend by.
  *
  * Some transactions, such as large extends and truncates, can be done
  * atomically all at once or in several stages.  The operation requests
  * a credit for a number of buffer modifications in advance, but can
  * extend its credit if it needs more.
  *
  * jbd2_journal_extend tries to give the running handle more buffer credits.
  * It does not guarantee that allocation - this is a best-effort only.
  * The calling process MUST be able to deal cleanly with a failure to
  * extend here.
  *
  * Return 0 on success, non-zero on failure.
  *
  * return code < 0 implies an error
  * return code > 0 implies normal transaction-full status.
  */
 int jbd2_journal_extend(handle_t *handle, int nblocks, int revoke_records)
@@ -728,41 +728,41 @@ static void stop_this_handle(handle_t *handle)
 			DIV_ROUND_UP(t_revokes - revokes, rr_per_blk);
 		handle->h_total_credits -= revoke_descriptors;
 	}
 	atomic_sub(handle->h_total_credits,
 		   &transaction->t_outstanding_credits);
 	if (handle->h_rsv_handle)
 		__jbd2_journal_unreserve_handle(handle->h_rsv_handle,
 						transaction);
 	if (atomic_dec_and_test(&transaction->t_updates))
 		wake_up(&journal->j_wait_updates);
 
 	rwsem_release(&journal->j_trans_commit_map, _THIS_IP_);
 	/*
 	 * Scope of the GFP_NOFS context is over here and so we can restore the
 	 * original alloc context.
 	 */
 	memalloc_nofs_restore(handle->saved_alloc_context);
 }
 
 /**
- * int jbd2_journal_restart() - restart a handle .
+ * jbd2__journal_restart() - restart a handle .
  * @handle:  handle to restart
  * @nblocks: nr credits requested
  * @revoke_records: number of revoke record credits requested
  * @gfp_mask: memory allocation flags (for start_this_handle)
  *
  * Restart a handle for a multi-transaction filesystem
  * operation.
  *
  * If the jbd2_journal_extend() call above fails to grant new buffer credits
  * to a running handle, a call to jbd2_journal_restart will commit the
  * handle's transaction so far and reattach the handle to a new
  * transaction capable of guaranteeing the requested number of
  * credits. We preserve reserved handle if there's any attached to the
  * passed in handle.
  */
 int jbd2__journal_restart(handle_t *handle, int nblocks, int revoke_records,
 			  gfp_t gfp_mask)
 {
 	transaction_t *transaction = handle->h_transaction;
 	journal_t *journal;
@@ -798,41 +798,41 @@ int jbd2__journal_restart(handle_t *handle, int nblocks, int revoke_records,
 		DIV_ROUND_UP(revoke_records,
 			     journal->j_revoke_records_per_block);
 	handle->h_revoke_credits = revoke_records;
 	ret = start_this_handle(journal, handle, gfp_mask);
 	trace_jbd2_handle_restart(journal->j_fs_dev->bd_dev,
 				 ret ? 0 : handle->h_transaction->t_tid,
 				 handle->h_type, handle->h_line_no,
 				 handle->h_total_credits);
 	return ret;
 }
 EXPORT_SYMBOL(jbd2__journal_restart);
 
 
 int jbd2_journal_restart(handle_t *handle, int nblocks)
 {
 	return jbd2__journal_restart(handle, nblocks, 0, GFP_NOFS);
 }
 EXPORT_SYMBOL(jbd2_journal_restart);
 
 /**
- * void jbd2_journal_lock_updates () - establish a transaction barrier.
+ * jbd2_journal_lock_updates () - establish a transaction barrier.
  * @journal:  Journal to establish a barrier on.
  *
  * This locks out any further updates from being started, and blocks
  * until all existing updates have completed, returning only once the
  * journal is in a quiescent state with no updates running.
  *
  * The journal lock should not be held on entry.
  */
 void jbd2_journal_lock_updates(journal_t *journal)
 {
 	DEFINE_WAIT(wait);
 
 	jbd2_might_wait_for_commit(journal);
 
 	write_lock(&journal->j_state_lock);
 	++journal->j_barrier_count;
 
 	/* Wait until there are no reserved handles */
 	if (atomic_read(&journal->j_reserved_credits)) {
 		write_unlock(&journal->j_state_lock);
@@ -857,41 +857,41 @@ void jbd2_journal_lock_updates(journal_t *journal)
 			break;
 		}
 		spin_unlock(&transaction->t_handle_lock);
 		write_unlock(&journal->j_state_lock);
 		schedule();
 		finish_wait(&journal->j_wait_updates, &wait);
 		write_lock(&journal->j_state_lock);
 	}
 	write_unlock(&journal->j_state_lock);
 
 	/*
 	 * We have now established a barrier against other normal updates, but
 	 * we also need to barrier against other jbd2_journal_lock_updates() calls
 	 * to make sure that we serialise special journal-locked operations
 	 * too.
 	 */
 	mutex_lock(&journal->j_barrier);
 }
 
 /**
- * void jbd2_journal_unlock_updates (journal_t* journal) - release barrier
+ * jbd2_journal_unlock_updates () - release barrier
  * @journal:  Journal to release the barrier on.
  *
  * Release a transaction barrier obtained with jbd2_journal_lock_updates().
  *
  * Should be called without the journal lock held.
  */
 void jbd2_journal_unlock_updates (journal_t *journal)
 {
 	J_ASSERT(journal->j_barrier_count != 0);
 
 	mutex_unlock(&journal->j_barrier);
 	write_lock(&journal->j_state_lock);
 	--journal->j_barrier_count;
 	write_unlock(&journal->j_state_lock);
 	wake_up(&journal->j_wait_transaction_locked);
 }
 
 static void warn_dirty_buffer(struct buffer_head *bh)
 {
 	printk(KERN_WARNING
@@ -1165,41 +1165,42 @@ static bool jbd2_write_access_granted(handle_t *handle, struct buffer_head *bh,
 		goto out;
 	/*
 	 * There are two reasons for the barrier here:
 	 * 1) Make sure to fetch b_bh after we did previous checks so that we
 	 * detect when jh went through free, realloc, attach to transaction
 	 * while we were checking. Paired with implicit barrier in that path.
 	 * 2) So that access to bh done after jbd2_write_access_granted()
 	 * doesn't get reordered and see inconsistent state of concurrent
 	 * do_get_write_access().
 	 */
 	smp_mb();
 	if (unlikely(jh->b_bh != bh))
 		goto out;
 	ret = true;
 out:
 	rcu_read_unlock();
 	return ret;
 }
 
 /**
- * int jbd2_journal_get_write_access() - notify intent to modify a buffer for metadata (not data) update.
+ * jbd2_journal_get_write_access() - notify intent to modify a buffer
+ *				     for metadata (not data) update.
  * @handle: transaction to add buffer modifications to
  * @bh:     bh to be used for metadata writes
  *
  * Returns: error code or 0 on success.
  *
  * In full data journalling mode the buffer may be of type BJ_AsyncData,
  * because we're ``write()ing`` a buffer which is also part of a shared mapping.
  */
 
 int jbd2_journal_get_write_access(handle_t *handle, struct buffer_head *bh)
 {
 	struct journal_head *jh;
 	int rc;
 
 	if (is_handle_aborted(handle))
 		return -EROFS;
 
 	if (jbd2_write_access_granted(handle, bh, false))
 		return 0;
 
@@ -1209,41 +1210,41 @@ int jbd2_journal_get_write_access(handle_t *handle, struct buffer_head *bh)
 	 * completes any outstanding IO before proceeding. */
 	rc = do_get_write_access(handle, jh, 0);
 	jbd2_journal_put_journal_head(jh);
 	return rc;
 }
 
 
 /*
  * When the user wants to journal a newly created buffer_head
  * (ie. getblk() returned a new buffer and we are going to populate it
  * manually rather than reading off disk), then we need to keep the
  * buffer_head locked until it has been completely filled with new
  * data.  In this case, we should be able to make the assertion that
  * the bh is not already part of an existing transaction.
  *
  * The buffer should already be locked by the caller by this point.
  * There is no lock ranking violation: it was a newly created,
  * unlocked buffer beforehand. */
 
 /**
- * int jbd2_journal_get_create_access () - notify intent to use newly created bh
+ * jbd2_journal_get_create_access () - notify intent to use newly created bh
  * @handle: transaction to new buffer to
  * @bh: new buffer.
  *
  * Call this if you create a new bh.
  */
 int jbd2_journal_get_create_access(handle_t *handle, struct buffer_head *bh)
 {
 	transaction_t *transaction = handle->h_transaction;
 	journal_t *journal;
 	struct journal_head *jh = jbd2_journal_add_journal_head(bh);
 	int err;
 
 	jbd_debug(5, "journal_head %p\n", jh);
 	err = -EROFS;
 	if (is_handle_aborted(handle))
 		goto out;
 	journal = transaction->t_journal;
 	err = 0;
 
 	JBUFFER_TRACE(jh, "entry");
@@ -1289,41 +1290,41 @@ int jbd2_journal_get_create_access(handle_t *handle, struct buffer_head *bh)
 		jh->b_next_transaction = transaction;
 		spin_unlock(&journal->j_list_lock);
 	}
 	spin_unlock(&jh->b_state_lock);
 
 	/*
 	 * akpm: I added this.  ext3_alloc_branch can pick up new indirect
 	 * blocks which contain freed but then revoked metadata.  We need
 	 * to cancel the revoke in case we end up freeing it yet again
 	 * and the reallocating as data - this would cause a second revoke,
 	 * which hits an assertion error.
 	 */
 	JBUFFER_TRACE(jh, "cancelling revoke");
 	jbd2_journal_cancel_revoke(handle, jh);
 out:
 	jbd2_journal_put_journal_head(jh);
 	return err;
 }
 
 /**
- * int jbd2_journal_get_undo_access() -  Notify intent to modify metadata with
+ * jbd2_journal_get_undo_access() -  Notify intent to modify metadata with
  *     non-rewindable consequences
  * @handle: transaction
  * @bh: buffer to undo
  *
  * Sometimes there is a need to distinguish between metadata which has
  * been committed to disk and that which has not.  The ext3fs code uses
  * this for freeing and allocating space, we have to make sure that we
  * do not reuse freed space until the deallocation has been committed,
  * since if we overwrote that space we would make the delete
  * un-rewindable in case of a crash.
  *
  * To deal with that, jbd2_journal_get_undo_access requests write access to a
  * buffer for parts of non-rewindable operations such as delete
  * operations on the bitmaps.  The journaling code must keep a copy of
  * the buffer's contents prior to the undo_access call until such time
  * as we know that the buffer has definitely been committed to disk.
  *
  * We never need to know which transaction the committed data is part
  * of, buffers touched here are guaranteed to be dirtied later and so
  * will be committed to a new transaction in due course, at which point
@@ -1366,41 +1367,41 @@ int jbd2_journal_get_undo_access(handle_t *handle, struct buffer_head *bh)
 		 * preserved, committed copy. */
 		JBUFFER_TRACE(jh, "generate b_committed data");
 		if (!committed_data) {
 			spin_unlock(&jh->b_state_lock);
 			goto repeat;
 		}
 
 		jh->b_committed_data = committed_data;
 		committed_data = NULL;
 		memcpy(jh->b_committed_data, bh->b_data, bh->b_size);
 	}
 	spin_unlock(&jh->b_state_lock);
 out:
 	jbd2_journal_put_journal_head(jh);
 	if (unlikely(committed_data))
 		jbd2_free(committed_data, bh->b_size);
 	return err;
 }
 
 /**
- * void jbd2_journal_set_triggers() - Add triggers for commit writeout
+ * jbd2_journal_set_triggers() - Add triggers for commit writeout
  * @bh: buffer to trigger on
  * @type: struct jbd2_buffer_trigger_type containing the trigger(s).
  *
  * Set any triggers on this journal_head.  This is always safe, because
  * triggers for a committing buffer will be saved off, and triggers for
  * a running transaction will match the buffer in that transaction.
  *
  * Call with NULL to clear the triggers.
  */
 void jbd2_journal_set_triggers(struct buffer_head *bh,
 			       struct jbd2_buffer_trigger_type *type)
 {
 	struct journal_head *jh = jbd2_journal_grab_journal_head(bh);
 
 	if (WARN_ON(!jh))
 		return;
 	jh->b_triggers = type;
 	jbd2_journal_put_journal_head(jh);
 }
 
@@ -1408,41 +1409,41 @@ void jbd2_buffer_frozen_trigger(struct journal_head *jh, void *mapped_data,
 				struct jbd2_buffer_trigger_type *triggers)
 {
 	struct buffer_head *bh = jh2bh(jh);
 
 	if (!triggers || !triggers->t_frozen)
 		return;
 
 	triggers->t_frozen(triggers, bh, mapped_data, bh->b_size);
 }
 
 void jbd2_buffer_abort_trigger(struct journal_head *jh,
 			       struct jbd2_buffer_trigger_type *triggers)
 {
 	if (!triggers || !triggers->t_abort)
 		return;
 
 	triggers->t_abort(triggers, jh2bh(jh));
 }
 
 /**
- * int jbd2_journal_dirty_metadata() -  mark a buffer as containing dirty metadata
+ * jbd2_journal_dirty_metadata() -  mark a buffer as containing dirty metadata
  * @handle: transaction to add buffer to.
  * @bh: buffer to mark
  *
  * mark dirty metadata which needs to be journaled as part of the current
  * transaction.
  *
  * The buffer must have previously had jbd2_journal_get_write_access()
  * called so that it has a valid journal_head attached to the buffer
  * head.
  *
  * The buffer is placed on the transaction's metadata list and is marked
  * as belonging to the transaction.
  *
  * Returns error number or 0 on success.
  *
  * Special care needs to be taken if the buffer already belongs to the
  * current committing transaction (in which case we should have frozen
  * data present for that commit).  In that case, we don't relink the
  * buffer: that only gets done when the old transaction finally
  * completes its commit.
@@ -1576,41 +1577,41 @@ int jbd2_journal_dirty_metadata(handle_t *handle, struct buffer_head *bh)
 		/* And this case is illegal: we can't reuse another
 		 * transaction's data buffer, ever. */
 		goto out_unlock_bh;
 	}
 
 	/* That test should have eliminated the following case: */
 	J_ASSERT_JH(jh, jh->b_frozen_data == NULL);
 
 	JBUFFER_TRACE(jh, "file as BJ_Metadata");
 	spin_lock(&journal->j_list_lock);
 	__jbd2_journal_file_buffer(jh, transaction, BJ_Metadata);
 	spin_unlock(&journal->j_list_lock);
 out_unlock_bh:
 	spin_unlock(&jh->b_state_lock);
 out:
 	JBUFFER_TRACE(jh, "exit");
 	return ret;
 }
 
 /**
- * void jbd2_journal_forget() - bforget() for potentially-journaled buffers.
+ * jbd2_journal_forget() - bforget() for potentially-journaled buffers.
  * @handle: transaction handle
  * @bh:     bh to 'forget'
  *
  * We can only do the bforget if there are no commits pending against the
  * buffer.  If the buffer is dirty in the current running transaction we
  * can safely unlink it.
  *
  * bh may not be a journalled buffer at all - it may be a non-JBD
  * buffer which came off the hashtable.  Check for this.
  *
  * Decrements bh->b_count by one.
  *
  * Allow this call even if the handle has aborted --- it may be part of
  * the caller's cleanup after an abort.
  */
 int jbd2_journal_forget(handle_t *handle, struct buffer_head *bh)
 {
 	transaction_t *transaction = handle->h_transaction;
 	journal_t *journal;
 	struct journal_head *jh;
@@ -1745,41 +1746,41 @@ int jbd2_journal_forget(handle_t *handle, struct buffer_head *bh)
 		 * attach this buffer to current transaction so that the
 		 * buffer can be checkpointed only after the current
 		 * transaction commits.
 		 */
 		clear_buffer_dirty(bh);
 		__jbd2_journal_file_buffer(jh, transaction, BJ_Forget);
 		spin_unlock(&journal->j_list_lock);
 	}
 drop:
 	__brelse(bh);
 	spin_unlock(&jh->b_state_lock);
 	jbd2_journal_put_journal_head(jh);
 	if (drop_reserve) {
 		/* no need to reserve log space for this block -bzzz */
 		handle->h_total_credits++;
 	}
 	return err;
 }
 
 /**
- * int jbd2_journal_stop() - complete a transaction
+ * jbd2_journal_stop() - complete a transaction
  * @handle: transaction to complete.
  *
  * All done for a particular handle.
  *
  * There is not much action needed here.  We just return any remaining
  * buffer credits to the transaction and remove the handle.  The only
  * complication is that we need to start a commit operation if the
  * filesystem is marked for synchronous update.
  *
  * jbd2_journal_stop itself will not usually return an error, but it may
  * do so in unusual circumstances.  In particular, expect it to
  * return -EIO if a jbd2_journal_abort has been executed since the
  * transaction began.
  */
 int jbd2_journal_stop(handle_t *handle)
 {
 	transaction_t *transaction = handle->h_transaction;
 	journal_t *journal;
 	int err = 0, wait_for_commit = 0;
 	tid_t tid;
@@ -2063,41 +2064,41 @@ __journal_try_to_free_buffer(journal_t *journal, struct buffer_head *bh)
 	jh = bh2jh(bh);
 
 	if (buffer_locked(bh) || buffer_dirty(bh))
 		goto out;
 
 	if (jh->b_next_transaction != NULL || jh->b_transaction != NULL)
 		goto out;
 
 	spin_lock(&journal->j_list_lock);
 	if (jh->b_cp_transaction != NULL) {
 		/* written-back checkpointed metadata buffer */
 		JBUFFER_TRACE(jh, "remove from checkpoint list");
 		__jbd2_journal_remove_checkpoint(jh);
 	}
 	spin_unlock(&journal->j_list_lock);
 out:
 	return;
 }
 
 /**
- * int jbd2_journal_try_to_free_buffers() - try to free page buffers.
+ * jbd2_journal_try_to_free_buffers() - try to free page buffers.
  * @journal: journal for operation
  * @page: to try and free
  *
  * For all the buffers on this page,
  * if they are fully written out ordered data, move them onto BUF_CLEAN
  * so try_to_free_buffers() can reap them.
  *
  * This function returns non-zero if we wish try_to_free_buffers()
  * to be called. We do this if the page is releasable by try_to_free_buffers().
  * We also do it if the page has locked or dirty buffers and the caller wants
  * us to perform sync or async writeout.
  *
  * This complicates JBD locking somewhat.  We aren't protected by the
  * BKL here.  We wish to remove the buffer from its committing or
  * running transaction's ->t_datalist via __jbd2_journal_unfile_buffer.
  *
  * This may *change* the value of transaction_t->t_datalist, so anyone
  * who looks at t_datalist needs to lock against this function.
  *
  * Even worse, someone may be doing a jbd2_journal_dirty_data on this
@@ -2394,41 +2395,41 @@ static int journal_unmap_buffer(journal_t *journal, struct buffer_head *bh,
 	 * here.
 	 */
 	jh->b_modified = 0;
 	spin_unlock(&journal->j_list_lock);
 	spin_unlock(&jh->b_state_lock);
 	write_unlock(&journal->j_state_lock);
 	jbd2_journal_put_journal_head(jh);
 zap_buffer_unlocked:
 	clear_buffer_dirty(bh);
 	J_ASSERT_BH(bh, !buffer_jbddirty(bh));
 	clear_buffer_mapped(bh);
 	clear_buffer_req(bh);
 	clear_buffer_new(bh);
 	clear_buffer_delay(bh);
 	clear_buffer_unwritten(bh);
 	bh->b_bdev = NULL;
 	return may_free;
 }
 
 /**
- * void jbd2_journal_invalidatepage()
+ * jbd2_journal_invalidatepage()
  * @journal: journal to use for flush...
  * @page:    page to flush
  * @offset:  start of the range to invalidate
  * @length:  length of the range to invalidate
  *
  * Reap page buffers containing data after in the specified range in page.
  * Can return -EBUSY if buffers are part of the committing transaction and
  * the page is straddling i_size. Caller then has to wait for current commit
  * and try again.
  */
 int jbd2_journal_invalidatepage(journal_t *journal,
 				struct page *page,
 				unsigned int offset,
 				unsigned int length)
 {
 	struct buffer_head *head, *bh, *next;
 	unsigned int stop = offset + length;
 	unsigned int curr_off = 0;
 	int partial_page = (offset || length < PAGE_SIZE);
 	int may_free = 1;
diff --git a/include/linux/jbd2.h b/include/linux/jbd2.h
index 1c49fd62ff2e..578ff196b3ce 100644
--- a/include/linux/jbd2.h
+++ b/include/linux/jbd2.h
@@ -384,41 +384,41 @@ static inline void jbd_unlock_bh_journal_head(struct buffer_head *bh)
 #define J_EXPECT_JH(jh, expr, why...)	__journal_expect(expr, ## why)
 #endif
 
 /* Flags in jbd_inode->i_flags */
 #define __JI_COMMIT_RUNNING 0
 #define __JI_WRITE_DATA 1
 #define __JI_WAIT_DATA 2
 
 /*
  * Commit of the inode data in progress. We use this flag to protect us from
  * concurrent deletion of inode. We cannot use reference to inode for this
  * since we cannot afford doing last iput() on behalf of kjournald
  */
 #define JI_COMMIT_RUNNING (1 << __JI_COMMIT_RUNNING)
 /* Write allocated dirty buffers in this inode before commit */
 #define JI_WRITE_DATA (1 << __JI_WRITE_DATA)
 /* Wait for outstanding data writes for this inode before commit */
 #define JI_WAIT_DATA (1 << __JI_WAIT_DATA)
 
 /**
- * struct jbd_inode - The jbd_inode type is the structure linking inodes in
+ * struct jbd2_inode - The jbd_inode type is the structure linking inodes in
  * ordered mode present in a transaction so that we can sync them during commit.
  */
 struct jbd2_inode {
 	/**
 	 * @i_transaction:
 	 *
 	 * Which transaction does this inode belong to? Either the running
 	 * transaction or the committing one. [j_list_lock]
 	 */
 	transaction_t *i_transaction;
 
 	/**
 	 * @i_next_transaction:
 	 *
 	 * Pointer to the running transaction modifying inode's data in case
 	 * there is already a committing transaction touching it. [j_list_lock]
 	 */
 	transaction_t *i_next_transaction;
 
 	/**
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 13/27] pstore/zone: fix a kernel-doc markup
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (11 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 12/27] jbd2: " Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 14/27] completion: fix kernel-doc markups Mauro Carvalho Chehab
                   ` (14 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Anton Vorontsov, Colin Cross, Kees Cook, Tony Luck
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-kernel

The documented struct is psz_head and not psz_buffer.

Reviewed-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 fs/pstore/zone.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/fs/pstore/zone.c b/fs/pstore/zone.c
index 3ce89216670c..46a1610c06fa 100644
--- a/fs/pstore/zone.c
+++ b/fs/pstore/zone.c
@@ -6,41 +6,41 @@
  */
 
 #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
 
 #include <linux/kernel.h>
 #include <linux/module.h>
 #include <linux/slab.h>
 #include <linux/mount.h>
 #include <linux/printk.h>
 #include <linux/fs.h>
 #include <linux/pstore_zone.h>
 #include <linux/kdev_t.h>
 #include <linux/device.h>
 #include <linux/namei.h>
 #include <linux/fcntl.h>
 #include <linux/uio.h>
 #include <linux/writeback.h>
 #include "internal.h"
 
 /**
- * struct psz_head - header of zone to flush to storage
+ * struct psz_buffer - header of zone to flush to storage
  *
  * @sig: signature to indicate header (PSZ_SIG xor PSZONE-type value)
  * @datalen: length of data in @data
  * @start: offset into @data where the beginning of the stored bytes begin
  * @data: zone data.
  */
 struct psz_buffer {
 #define PSZ_SIG (0x43474244) /* DBGC */
 	uint32_t sig;
 	atomic_t datalen;
 	atomic_t start;
 	uint8_t data[];
 };
 
 /**
  * struct psz_kmsg_header - kmsg dump-specific header to flush to storage
  *
  * @magic: magic num for kmsg dump header
  * @time: kmsg dump trigger time
  * @compressed: whether conpressed
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 14/27] completion: fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (12 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 13/27] pstore/zone: fix a kernel-doc markup Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 11:36   ` Peter Zijlstra
  2020-11-16 10:18 ` [PATCH v4 15/27] firmware: stratix10-svc: " Mauro Carvalho Chehab
                   ` (13 subsequent siblings)
  27 siblings, 1 reply; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Joel Fernandes (Google),
	Jonathan Corbet, Peter Zijlstra (Intel),
	Davidlohr Bueso, Greg Kroah-Hartman, Thomas Gleixner,
	linux-kernel

Kernel-doc only supports having the comment just before
the identifier.

The markup for init_completion is actually for
__init_completion.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

---

Thats said, IMHO, it would make sense to simply
rename __init_completion() to init_completion() and drop
this define:

	 #define init_completion(x) __init_completion(x)

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

diff --git a/include/linux/completion.h b/include/linux/completion.h
index bf8e77001f18..ff354918dbf4 100644
--- a/include/linux/completion.h
+++ b/include/linux/completion.h
@@ -12,40 +12,48 @@
 #include <linux/swait.h>
 
 /*
  * struct completion - structure used to maintain state for a "completion"
  *
  * This is the opaque structure used to maintain the state for a "completion".
  * Completions currently use a FIFO to queue threads that have to wait for
  * the "completion" event.
  *
  * See also:  complete(), wait_for_completion() (and friends _timeout,
  * _interruptible, _interruptible_timeout, and _killable), init_completion(),
  * reinit_completion(), and macros DECLARE_COMPLETION(),
  * DECLARE_COMPLETION_ONSTACK().
  */
 struct completion {
 	unsigned int done;
 	struct swait_queue_head wait;
 };
 
 #define init_completion_map(x, m) __init_completion(x)
+
+/**
+ * init_completion - Initialize a dynamically allocated completion
+ * @x:  pointer to completion structure that is to be initialized
+ *
+ * This macro will initialize a dynamically created completion
+ * structure.
+ */
 #define init_completion(x) __init_completion(x)
 static inline void complete_acquire(struct completion *x) {}
 static inline void complete_release(struct completion *x) {}
 
 #define COMPLETION_INITIALIZER(work) \
 	{ 0, __SWAIT_QUEUE_HEAD_INITIALIZER((work).wait) }
 
 #define COMPLETION_INITIALIZER_ONSTACK_MAP(work, map) \
 	(*({ init_completion_map(&(work), &(map)); &(work); }))
 
 #define COMPLETION_INITIALIZER_ONSTACK(work) \
 	(*({ init_completion(&work); &work; }))
 
 /**
  * DECLARE_COMPLETION - declare and initialize a completion structure
  * @work:  identifier for the completion structure
  *
  * This macro declares and initializes a completion structure. Generally used
  * for static declarations. You should use the _ONSTACK variant for automatic
  * variables.
@@ -59,41 +67,41 @@ static inline void complete_release(struct completion *x) {}
  * are on the kernel stack:
  */
 /**
  * DECLARE_COMPLETION_ONSTACK - declare and initialize a completion structure
  * @work:  identifier for the completion structure
  *
  * This macro declares and initializes a completion structure on the kernel
  * stack.
  */
 #ifdef CONFIG_LOCKDEP
 # define DECLARE_COMPLETION_ONSTACK(work) \
 	struct completion work = COMPLETION_INITIALIZER_ONSTACK(work)
 # define DECLARE_COMPLETION_ONSTACK_MAP(work, map) \
 	struct completion work = COMPLETION_INITIALIZER_ONSTACK_MAP(work, map)
 #else
 # define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work)
 # define DECLARE_COMPLETION_ONSTACK_MAP(work, map) DECLARE_COMPLETION(work)
 #endif
 
 /**
- * init_completion - Initialize a dynamically allocated completion
+ * __init_completion - Initialize a dynamically allocated completion
  * @x:  pointer to completion structure that is to be initialized
  *
  * This inline function will initialize a dynamically created completion
  * structure.
  */
 static inline void __init_completion(struct completion *x)
 {
 	x->done = 0;
 	init_swait_queue_head(&x->wait);
 }
 
 /**
  * reinit_completion - reinitialize a completion structure
  * @x:  pointer to completion structure that is to be reinitialized
  *
  * This inline function should be used to reinitialize a completion structure so it can
  * be reused. This is especially important after complete_all() is used.
  */
 static inline void reinit_completion(struct completion *x)
 {
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 15/27] firmware: stratix10-svc: fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (13 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 14/27] completion: fix kernel-doc markups Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 16/27] connector: fix a kernel-doc markup Mauro Carvalho Chehab
                   ` (12 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Richard Gong
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-kernel

There are some common comments marked, instead, with kernel-doc
notation, which won't work.

While here, rename an identifier, in order to match the
function prototype below kernel-doc markup.

Acked-by: Richard Gong <richard.gong@linux.intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/firmware/intel/stratix10-svc-client.h | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/include/linux/firmware/intel/stratix10-svc-client.h b/include/linux/firmware/intel/stratix10-svc-client.h
index a93d85932eb9..ebc295647581 100644
--- a/include/linux/firmware/intel/stratix10-svc-client.h
+++ b/include/linux/firmware/intel/stratix10-svc-client.h
@@ -1,81 +1,81 @@
 /* SPDX-License-Identifier: GPL-2.0 */
 /*
  * Copyright (C) 2017-2018, Intel Corporation
  */
 
 #ifndef __STRATIX10_SVC_CLIENT_H
 #define __STRATIX10_SVC_CLIENT_H
 
-/**
+/*
  * Service layer driver supports client names
  *
  * fpga: for FPGA configuration
  * rsu: for remote status update
  */
 #define SVC_CLIENT_FPGA			"fpga"
 #define SVC_CLIENT_RSU			"rsu"
 
-/**
+/*
  * Status of the sent command, in bit number
  *
  * SVC_STATUS_OK:
  * Secure firmware accepts the request issued by one of service clients.
  *
  * SVC_STATUS_BUFFER_SUBMITTED:
  * Service client successfully submits data buffer to secure firmware.
  *
  * SVC_STATUS_BUFFER_DONE:
  * Secure firmware completes data process, ready to accept the
  * next WRITE transaction.
  *
  * SVC_STATUS_COMPLETED:
  * Secure firmware completes service request successfully. In case of
  * FPGA configuration, FPGA should be in user mode.
  *
  * SVC_COMMAND_STATUS_BUSY:
  * Service request is still in process.
  *
  * SVC_COMMAND_STATUS_ERROR:
  * Error encountered during the process of the service request.
  *
  * SVC_STATUS_NO_SUPPORT:
  * Secure firmware doesn't support requested features such as RSU retry
  * or RSU notify.
  */
 #define SVC_STATUS_OK			0
 #define SVC_STATUS_BUFFER_SUBMITTED	1
 #define SVC_STATUS_BUFFER_DONE		2
 #define SVC_STATUS_COMPLETED		3
 #define SVC_STATUS_BUSY			4
 #define SVC_STATUS_ERROR		5
 #define SVC_STATUS_NO_SUPPORT		6
 
-/**
+/*
  * Flag bit for COMMAND_RECONFIG
  *
  * COMMAND_RECONFIG_FLAG_PARTIAL:
  * Set to FPGA configuration type (full or partial).
  */
 #define COMMAND_RECONFIG_FLAG_PARTIAL	1
 
-/**
+/*
  * Timeout settings for service clients:
  * timeout value used in Stratix10 FPGA manager driver.
  * timeout value used in RSU driver
  */
 #define SVC_RECONFIG_REQUEST_TIMEOUT_MS         300
 #define SVC_RECONFIG_BUFFER_TIMEOUT_MS          720
 #define SVC_RSU_REQUEST_TIMEOUT_MS              300
 
 struct stratix10_svc_chan;
 
 /**
  * enum stratix10_svc_command_code - supported service commands
  *
  * @COMMAND_NOOP: do 'dummy' request for integration/debug/trouble-shooting
  *
  * @COMMAND_RECONFIG: ask for FPGA configuration preparation, return status
  * is SVC_STATUS_OK
  *
  * @COMMAND_RECONFIG_DATA_SUBMIT: submit buffer(s) of bit-stream data for the
  * FPGA configuration, return status is SVC_STATUS_SUBMITTED or SVC_STATUS_ERROR
@@ -201,30 +201,30 @@ void *stratix10_svc_allocate_memory(struct stratix10_svc_chan *chan,
 				    size_t size);
 
 /**
  * stratix10_svc_free_memory() - free allocated memory
  * @chan: service channel assigned to the client
  * @kaddr: starting address of memory to be free back to pool
  */
 void stratix10_svc_free_memory(struct stratix10_svc_chan *chan, void *kaddr);
 
 /**
  * stratix10_svc_send() - send a message to the remote
  * @chan: service channel assigned to the client
  * @msg: message data to be sent, in the format of
  * struct stratix10_svc_client_msg
  *
  * Return: 0 for success, -ENOMEM or -ENOBUFS on error.
  */
 int stratix10_svc_send(struct stratix10_svc_chan *chan, void *msg);
 
 /**
- * intel_svc_done() - complete service request
+ * stratix10_svc_done() - complete service request
  * @chan: service channel assigned to the client
  *
  * This function is used by service client to inform service layer that
  * client's service requests are completed, or there is an error in the
  * request process.
  */
 void stratix10_svc_done(struct stratix10_svc_chan *chan);
 #endif
 
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 16/27] connector: fix a kernel-doc markup
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (14 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 15/27] firmware: stratix10-svc: " Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 17/27] lib/crc7: " Mauro Carvalho Chehab
                   ` (11 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-kernel

A function has a different name between their prototype
and its kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/connector.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/connector.h b/include/linux/connector.h
index cb732643471b..6bdb56662675 100644
--- a/include/linux/connector.h
+++ b/include/linux/connector.h
@@ -82,41 +82,41 @@ void cn_del_callback(struct cb_id *id);
  * @portid:	destination port.
  *		If non-zero the message will be sent to the given port,
  *		which should be set to the original sender.
  * @group:	destination group.
  * 		If @portid and @group is zero, then appropriate group will
  *		be searched through all registered connector users, and
  *		message will be delivered to the group which was created
  *		for user with the same ID as in @msg.
  *		If @group is not zero, then message will be delivered
  *		to the specified group.
  * @gfp_mask:	GFP mask.
  *
  * It can be safely called from softirq context, but may silently
  * fail under strong memory pressure.
  *
  * If there are no listeners for given group %-ESRCH can be returned.
  */
 int cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 group, gfp_t gfp_mask);
 
 /**
- * cn_netlink_send_mult - Sends message to the specified groups.
+ * cn_netlink_send - Sends message to the specified groups.
  *
  * @msg:	message header(with attached data).
  * @portid:	destination port.
  *		If non-zero the message will be sent to the given port,
  *		which should be set to the original sender.
  * @group:	destination group.
  * 		If @portid and @group is zero, then appropriate group will
  *		be searched through all registered connector users, and
  *		message will be delivered to the group which was created
  *		for user with the same ID as in @msg.
  *		If @group is not zero, then message will be delivered
  *		to the specified group.
  * @gfp_mask:	GFP mask.
  *
  * It can be safely called from softirq context, but may silently
  * fail under strong memory pressure.
  *
  * If there are no listeners for given group %-ESRCH can be returned.
  */
 int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 group, gfp_t gfp_mask);
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 17/27] lib/crc7: fix a kernel-doc markup
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (15 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 16/27] connector: fix a kernel-doc markup Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 18/27] hrtimer: fix kernel-doc markups Mauro Carvalho Chehab
                   ` (10 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-kernel

A function has a different name between their prototype
and its kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 lib/crc7.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/crc7.c b/lib/crc7.c
index 6a848d73e804..3848e313b722 100644
--- a/lib/crc7.c
+++ b/lib/crc7.c
@@ -34,41 +34,41 @@ const u8 crc7_be_syndrome_table[256] = {
 	0x82, 0x90, 0xa6, 0xb4, 0xca, 0xd8, 0xee, 0xfc,
 	0x12, 0x00, 0x36, 0x24, 0x5a, 0x48, 0x7e, 0x6c,
 	0xb0, 0xa2, 0x94, 0x86, 0xf8, 0xea, 0xdc, 0xce,
 	0x20, 0x32, 0x04, 0x16, 0x68, 0x7a, 0x4c, 0x5e,
 	0xe6, 0xf4, 0xc2, 0xd0, 0xae, 0xbc, 0x8a, 0x98,
 	0x76, 0x64, 0x52, 0x40, 0x3e, 0x2c, 0x1a, 0x08,
 	0xd4, 0xc6, 0xf0, 0xe2, 0x9c, 0x8e, 0xb8, 0xaa,
 	0x44, 0x56, 0x60, 0x72, 0x0c, 0x1e, 0x28, 0x3a,
 	0x4a, 0x58, 0x6e, 0x7c, 0x02, 0x10, 0x26, 0x34,
 	0xda, 0xc8, 0xfe, 0xec, 0x92, 0x80, 0xb6, 0xa4,
 	0x78, 0x6a, 0x5c, 0x4e, 0x30, 0x22, 0x14, 0x06,
 	0xe8, 0xfa, 0xcc, 0xde, 0xa0, 0xb2, 0x84, 0x96,
 	0x2e, 0x3c, 0x0a, 0x18, 0x66, 0x74, 0x42, 0x50,
 	0xbe, 0xac, 0x9a, 0x88, 0xf6, 0xe4, 0xd2, 0xc0,
 	0x1c, 0x0e, 0x38, 0x2a, 0x54, 0x46, 0x70, 0x62,
 	0x8c, 0x9e, 0xa8, 0xba, 0xc4, 0xd6, 0xe0, 0xf2
 };
 EXPORT_SYMBOL(crc7_be_syndrome_table);
 
 /**
- * crc7 - update the CRC7 for the data buffer
+ * crc7_be - update the CRC7 for the data buffer
  * @crc:     previous CRC7 value
  * @buffer:  data pointer
  * @len:     number of bytes in the buffer
  * Context: any
  *
  * Returns the updated CRC7 value.
  * The CRC7 is left-aligned in the byte (the lsbit is always 0), as that
  * makes the computation easier, and all callers want it in that form.
  *
  */
 u8 crc7_be(u8 crc, const u8 *buffer, size_t len)
 {
 	while (len--)
 		crc = crc7_be_byte(crc, *buffer++);
 	return crc;
 }
 EXPORT_SYMBOL(crc7_be);
 
 MODULE_DESCRIPTION("CRC7 calculations");
 MODULE_LICENSE("GPL");
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 18/27] hrtimer: fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (16 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 17/27] lib/crc7: " Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 19/27] genirq: " Mauro Carvalho Chehab
                   ` (9 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Thomas Gleixner
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-kernel

The hrtimer_get_remaining() markup is documenting, instead,
__hrtimer_get_remaining(), as it is placed at the C file.

In order to properly document it, a kernel-doc markup is
needed together with the function prototype. So, add a
new one, while preserving the existing one, just fixing
the function name.

The hrtimer_is_queued prototype has a typo: it is using
'=' character instead of '-' to split:
	        identifier - description

as required by kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/hrtimer.h | 6 +++++-
 kernel/time/hrtimer.c   | 2 +-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/include/linux/hrtimer.h b/include/linux/hrtimer.h
index 107cedd7019a..bb5e7b0a4274 100644
--- a/include/linux/hrtimer.h
+++ b/include/linux/hrtimer.h
@@ -430,52 +430,56 @@ static inline void hrtimer_start_expires(struct hrtimer *timer,
 {
 	u64 delta;
 	ktime_t soft, hard;
 	soft = hrtimer_get_softexpires(timer);
 	hard = hrtimer_get_expires(timer);
 	delta = ktime_to_ns(ktime_sub(hard, soft));
 	hrtimer_start_range_ns(timer, soft, delta, mode);
 }
 
 void hrtimer_sleeper_start_expires(struct hrtimer_sleeper *sl,
 				   enum hrtimer_mode mode);
 
 static inline void hrtimer_restart(struct hrtimer *timer)
 {
 	hrtimer_start_expires(timer, HRTIMER_MODE_ABS);
 }
 
 /* Query timers: */
 extern ktime_t __hrtimer_get_remaining(const struct hrtimer *timer, bool adjust);
 
+/**
+ * hrtimer_get_remaining - get remaining time for the timer
+ * @timer:	the timer to read
+ */
 static inline ktime_t hrtimer_get_remaining(const struct hrtimer *timer)
 {
 	return __hrtimer_get_remaining(timer, false);
 }
 
 extern u64 hrtimer_get_next_event(void);
 extern u64 hrtimer_next_event_without(const struct hrtimer *exclude);
 
 extern bool hrtimer_active(const struct hrtimer *timer);
 
 /**
- * hrtimer_is_queued = check, whether the timer is on one of the queues
+ * hrtimer_is_queued - check, whether the timer is on one of the queues
  * @timer:	Timer to check
  *
  * Returns: True if the timer is queued, false otherwise
  *
  * The function can be used lockless, but it gives only a current snapshot.
  */
 static inline bool hrtimer_is_queued(struct hrtimer *timer)
 {
 	/* The READ_ONCE pairs with the update functions of timer->state */
 	return !!(READ_ONCE(timer->state) & HRTIMER_STATE_ENQUEUED);
 }
 
 /*
  * Helper function to check, whether the timer is running the callback
  * function
  */
 static inline int hrtimer_callback_running(struct hrtimer *timer)
 {
 	return timer->base->running == timer;
 }
diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
index 387b4bef7dd1..743c852e10f2 100644
--- a/kernel/time/hrtimer.c
+++ b/kernel/time/hrtimer.c
@@ -1267,41 +1267,41 @@ static inline void hrtimer_sync_wait_running(struct hrtimer_cpu_base *base,
  *
  * Returns:
  *  0 when the timer was not active
  *  1 when the timer was active
  */
 int hrtimer_cancel(struct hrtimer *timer)
 {
 	int ret;
 
 	do {
 		ret = hrtimer_try_to_cancel(timer);
 
 		if (ret < 0)
 			hrtimer_cancel_wait_running(timer);
 	} while (ret < 0);
 	return ret;
 }
 EXPORT_SYMBOL_GPL(hrtimer_cancel);
 
 /**
- * hrtimer_get_remaining - get remaining time for the timer
+ * __hrtimer_get_remaining - get remaining time for the timer
  * @timer:	the timer to read
  * @adjust:	adjust relative timers when CONFIG_TIME_LOW_RES=y
  */
 ktime_t __hrtimer_get_remaining(const struct hrtimer *timer, bool adjust)
 {
 	unsigned long flags;
 	ktime_t rem;
 
 	lock_hrtimer_base(timer, &flags);
 	if (IS_ENABLED(CONFIG_TIME_LOW_RES) && adjust)
 		rem = hrtimer_expires_remaining_adjusted(timer);
 	else
 		rem = hrtimer_expires_remaining(timer);
 	unlock_hrtimer_base(timer, &flags);
 
 	return rem;
 }
 EXPORT_SYMBOL_GPL(__hrtimer_get_remaining);
 
 #ifdef CONFIG_NO_HZ_COMMON
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 19/27] genirq: fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (17 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 18/27] hrtimer: fix kernel-doc markups Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 20/27] list: fix a typo at the kernel-doc markup Mauro Carvalho Chehab
                   ` (8 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Thomas Gleixner
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-kernel

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 kernel/irq/chip.c         | 2 +-
 kernel/irq/generic-chip.c | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/kernel/irq/chip.c b/kernel/irq/chip.c
index b9b9618e1aca..df75c3573dcb 100644
--- a/kernel/irq/chip.c
+++ b/kernel/irq/chip.c
@@ -44,41 +44,41 @@ int irq_set_chip(unsigned int irq, struct irq_chip *chip)
 	struct irq_desc *desc = irq_get_desc_lock(irq, &flags, 0);
 
 	if (!desc)
 		return -EINVAL;
 
 	if (!chip)
 		chip = &no_irq_chip;
 
 	desc->irq_data.chip = chip;
 	irq_put_desc_unlock(desc, flags);
 	/*
 	 * For !CONFIG_SPARSE_IRQ make the irq show up in
 	 * allocated_irqs.
 	 */
 	irq_mark_irq(irq);
 	return 0;
 }
 EXPORT_SYMBOL(irq_set_chip);
 
 /**
- *	irq_set_type - set the irq trigger type for an irq
+ *	irq_set_irq_type - set the irq trigger type for an irq
  *	@irq:	irq number
  *	@type:	IRQ_TYPE_{LEVEL,EDGE}_* value - see include/linux/irq.h
  */
 int irq_set_irq_type(unsigned int irq, unsigned int type)
 {
 	unsigned long flags;
 	struct irq_desc *desc = irq_get_desc_buslock(irq, &flags, IRQ_GET_DESC_CHECK_GLOBAL);
 	int ret = 0;
 
 	if (!desc)
 		return -EINVAL;
 
 	ret = __irq_set_trigger(desc, type);
 	irq_put_desc_busunlock(desc, flags);
 	return ret;
 }
 EXPORT_SYMBOL(irq_set_irq_type);
 
 /**
  *	irq_set_handler_data - set irq handler data for an irq
diff --git a/kernel/irq/generic-chip.c b/kernel/irq/generic-chip.c
index e2999a070a99..a23ac2bbf433 100644
--- a/kernel/irq/generic-chip.c
+++ b/kernel/irq/generic-chip.c
@@ -252,41 +252,41 @@ EXPORT_SYMBOL_GPL(irq_alloc_generic_chip);
 
 static void
 irq_gc_init_mask_cache(struct irq_chip_generic *gc, enum irq_gc_flags flags)
 {
 	struct irq_chip_type *ct = gc->chip_types;
 	u32 *mskptr = &gc->mask_cache, mskreg = ct->regs.mask;
 	int i;
 
 	for (i = 0; i < gc->num_ct; i++) {
 		if (flags & IRQ_GC_MASK_CACHE_PER_TYPE) {
 			mskptr = &ct[i].mask_cache_priv;
 			mskreg = ct[i].regs.mask;
 		}
 		ct[i].mask_cache = mskptr;
 		if (flags & IRQ_GC_INIT_MASK_CACHE)
 			*mskptr = irq_reg_readl(gc, mskreg);
 	}
 }
 
 /**
- * __irq_alloc_domain_generic_chip - Allocate generic chips for an irq domain
+ * __irq_alloc_domain_generic_chips - Allocate generic chips for an irq domain
  * @d:			irq domain for which to allocate chips
  * @irqs_per_chip:	Number of interrupts each chip handles (max 32)
  * @num_ct:		Number of irq_chip_type instances associated with this
  * @name:		Name of the irq chip
  * @handler:		Default flow handler associated with these chips
  * @clr:		IRQ_* bits to clear in the mapping function
  * @set:		IRQ_* bits to set in the mapping function
  * @gcflags:		Generic chip specific setup flags
  */
 int __irq_alloc_domain_generic_chips(struct irq_domain *d, int irqs_per_chip,
 				     int num_ct, const char *name,
 				     irq_flow_handler_t handler,
 				     unsigned int clr, unsigned int set,
 				     enum irq_gc_flags gcflags)
 {
 	struct irq_domain_chip_generic *dgc;
 	struct irq_chip_generic *gc;
 	int numchips, sz, i;
 	unsigned long flags;
 	void *tmp;
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 20/27] list: fix a typo at the kernel-doc markup
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (18 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 19/27] genirq: " Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 19:57   ` Paul E. McKenney
  2020-11-16 10:18 ` [PATCH v4 21/27] memblock: fix kernel-doc markups Mauro Carvalho Chehab
                   ` (7 subsequent siblings)
  27 siblings, 1 reply; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Paul E. McKenney,
	Andrew Morton, Andy Shevchenko, Asif Rasheed, Eric Dumazet,
	Pavel Begunkov, linux-kernel

hlist_add_behing -> hlist_add_behind

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/list.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/list.h b/include/linux/list.h
index 89bdc92e75c3..f2af4b4aa4e9 100644
--- a/include/linux/list.h
+++ b/include/linux/list.h
@@ -884,41 +884,41 @@ static inline void hlist_add_head(struct hlist_node *n, struct hlist_head *h)
 		WRITE_ONCE(first->pprev, &n->next);
 	WRITE_ONCE(h->first, n);
 	WRITE_ONCE(n->pprev, &h->first);
 }
 
 /**
  * hlist_add_before - add a new entry before the one specified
  * @n: new entry to be added
  * @next: hlist node to add it before, which must be non-NULL
  */
 static inline void hlist_add_before(struct hlist_node *n,
 				    struct hlist_node *next)
 {
 	WRITE_ONCE(n->pprev, next->pprev);
 	WRITE_ONCE(n->next, next);
 	WRITE_ONCE(next->pprev, &n->next);
 	WRITE_ONCE(*(n->pprev), n);
 }
 
 /**
- * hlist_add_behing - add a new entry after the one specified
+ * hlist_add_behind - add a new entry after the one specified
  * @n: new entry to be added
  * @prev: hlist node to add it after, which must be non-NULL
  */
 static inline void hlist_add_behind(struct hlist_node *n,
 				    struct hlist_node *prev)
 {
 	WRITE_ONCE(n->next, prev->next);
 	WRITE_ONCE(prev->next, n);
 	WRITE_ONCE(n->pprev, &prev->next);
 
 	if (n->next)
 		WRITE_ONCE(n->next->pprev, &n->next);
 }
 
 /**
  * hlist_add_fake - create a fake hlist consisting of a single headless node
  * @n: Node to make a fake list out of
  *
  * This makes @n appear to be its own predecessor on a headless hlist.
  * The point of this is to allow things like hlist_del() to work correctly
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 21/27] memblock: fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (19 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 20/27] list: fix a typo at the kernel-doc markup Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 22/27] w1: fix a kernel-doc markup Mauro Carvalho Chehab
                   ` (6 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Mike Rapoport
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-kernel, linux-mm, Mike Rapoport

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

Acked-by: Mike Rapoport <rppt@linux.ibm.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/memblock.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/linux/memblock.h b/include/linux/memblock.h
index ef131255cedc..95fe3cb71c54 100644
--- a/include/linux/memblock.h
+++ b/include/linux/memblock.h
@@ -255,61 +255,61 @@ void __next_mem_pfn_range(int *idx, int nid, unsigned long *out_start_pfn,
 
 /**
  * for_each_mem_pfn_range - early memory pfn range iterator
  * @i: an integer used as loop variable
  * @nid: node selector, %MAX_NUMNODES for all nodes
  * @p_start: ptr to ulong for start pfn of the range, can be %NULL
  * @p_end: ptr to ulong for end pfn of the range, can be %NULL
  * @p_nid: ptr to int for nid of the range, can be %NULL
  *
  * Walks over configured memory ranges.
  */
 #define for_each_mem_pfn_range(i, nid, p_start, p_end, p_nid)		\
 	for (i = -1, __next_mem_pfn_range(&i, nid, p_start, p_end, p_nid); \
 	     i >= 0; __next_mem_pfn_range(&i, nid, p_start, p_end, p_nid))
 
 #ifdef CONFIG_DEFERRED_STRUCT_PAGE_INIT
 void __next_mem_pfn_range_in_zone(u64 *idx, struct zone *zone,
 				  unsigned long *out_spfn,
 				  unsigned long *out_epfn);
 /**
- * for_each_free_mem_range_in_zone - iterate through zone specific free
+ * for_each_free_mem_pfn_range_in_zone - iterate through zone specific free
  * memblock areas
  * @i: u64 used as loop variable
  * @zone: zone in which all of the memory blocks reside
  * @p_start: ptr to phys_addr_t for start address of the range, can be %NULL
  * @p_end: ptr to phys_addr_t for end address of the range, can be %NULL
  *
  * Walks over free (memory && !reserved) areas of memblock in a specific
  * zone. Available once memblock and an empty zone is initialized. The main
  * assumption is that the zone start, end, and pgdat have been associated.
  * This way we can use the zone to determine NUMA node, and if a given part
  * of the memblock is valid for the zone.
  */
 #define for_each_free_mem_pfn_range_in_zone(i, zone, p_start, p_end)	\
 	for (i = 0,							\
 	     __next_mem_pfn_range_in_zone(&i, zone, p_start, p_end);	\
 	     i != U64_MAX;					\
 	     __next_mem_pfn_range_in_zone(&i, zone, p_start, p_end))
 
 /**
- * for_each_free_mem_range_in_zone_from - iterate through zone specific
+ * for_each_free_mem_pfn_range_in_zone_from - iterate through zone specific
  * free memblock areas from a given point
  * @i: u64 used as loop variable
  * @zone: zone in which all of the memory blocks reside
  * @p_start: ptr to phys_addr_t for start address of the range, can be %NULL
  * @p_end: ptr to phys_addr_t for end address of the range, can be %NULL
  *
  * Walks over free (memory && !reserved) areas of memblock in a specific
  * zone, continuing from current position. Available as soon as memblock is
  * initialized.
  */
 #define for_each_free_mem_pfn_range_in_zone_from(i, zone, p_start, p_end) \
 	for (; i != U64_MAX;					  \
 	     __next_mem_pfn_range_in_zone(&i, zone, p_start, p_end))
 
 int __init deferred_page_init_max_threads(const struct cpumask *node_cpumask);
 
 #endif /* CONFIG_DEFERRED_STRUCT_PAGE_INIT */
 
 /**
  * for_each_free_mem_range - iterate through free memblock areas
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 22/27] w1: fix a kernel-doc markup
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (20 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 21/27] memblock: fix kernel-doc markups Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 23/27] resource: fix kernel-doc markups Mauro Carvalho Chehab
                   ` (5 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Evgeniy Polyakov
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-kernel

A function has a different name between their prototype
and its kernel-doc markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/linux/w1.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/w1.h b/include/linux/w1.h
index 949d3b10e531..9a2a0ef39018 100644
--- a/include/linux/w1.h
+++ b/include/linux/w1.h
@@ -263,41 +263,41 @@ struct w1_family_ops {
  * @fid:		8 bit family identifier
  * @fops:		operations for this family
  * @of_match_table: open firmware match table
  * @refcnt:		reference counter
  */
 struct w1_family {
 	struct list_head	family_entry;
 	u8			fid;
 
 	const struct w1_family_ops *fops;
 
 	const struct of_device_id *of_match_table;
 
 	atomic_t		refcnt;
 };
 
 int w1_register_family(struct w1_family *family);
 void w1_unregister_family(struct w1_family *family);
 
 /**
- * module_w1_driver() - Helper macro for registering a 1-Wire families
+ * module_w1_family() - Helper macro for registering a 1-Wire families
  * @__w1_family: w1_family struct
  *
  * Helper macro for 1-Wire families which do not do anything special in module
  * init/exit. This eliminates a lot of boilerplate. Each module may only
  * use this macro once, and calling it replaces module_init() and module_exit()
  */
 #define module_w1_family(__w1_family) \
 	module_driver(__w1_family, w1_register_family, \
 			w1_unregister_family)
 
 u8 w1_triplet(struct w1_master *dev, int bdir);
 u8 w1_touch_bit(struct w1_master *dev, int bit);
 void w1_write_8(struct w1_master *, u8);
 u8 w1_read_8(struct w1_master *);
 int w1_reset_bus(struct w1_master *);
 u8 w1_calc_crc8(u8 *, int);
 void w1_write_block(struct w1_master *, const u8 *, int);
 void w1_touch_block(struct w1_master *, u8 *, int);
 u8 w1_read_block(struct w1_master *, u8 *, int);
 int w1_reset_select_slave(struct w1_slave *sl);
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 23/27] resource: fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (21 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 22/27] w1: fix a kernel-doc markup Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 24/27] shed: fix kernel-doc markup Mauro Carvalho Chehab
                   ` (4 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Andrew Morton,
	Dan Williams, David Hildenbrand, Greg Kroah-Hartman, Wei Yang,
	linux-kernel

Kernel-doc markups should use this format:
        identifier - description

While here, fix a kernel-doc tag that was using, instead,
a normal comment block.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 kernel/resource.c | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/kernel/resource.c b/kernel/resource.c
index 3ae2f56cc79d..9738920abdca 100644
--- a/kernel/resource.c
+++ b/kernel/resource.c
@@ -303,57 +303,59 @@ int request_resource(struct resource *root, struct resource *new)
 
 EXPORT_SYMBOL(request_resource);
 
 /**
  * release_resource - release a previously reserved resource
  * @old: resource pointer
  */
 int release_resource(struct resource *old)
 {
 	int retval;
 
 	write_lock(&resource_lock);
 	retval = __release_resource(old, true);
 	write_unlock(&resource_lock);
 	return retval;
 }
 
 EXPORT_SYMBOL(release_resource);
 
 /**
- * Finds the lowest iomem resource that covers part of [@start..@end].  The
- * caller must specify @start, @end, @flags, and @desc (which may be
- * IORES_DESC_NONE).
+ * find_next_iomem_res - Finds the lowest iomem resource that covers part of
+ *			 [@start..@end].
  *
  * If a resource is found, returns 0 and @*res is overwritten with the part
  * of the resource that's within [@start..@end]; if none is found, returns
  * -ENODEV.  Returns -EINVAL for invalid parameters.
  *
  * This function walks the whole tree and not just first level children
  * unless @first_lvl is true.
  *
  * @start:	start address of the resource searched for
  * @end:	end address of same resource
  * @flags:	flags which the resource must have
  * @desc:	descriptor the resource must have
  * @first_lvl:	walk only the first level children, if set
  * @res:	return ptr, if resource found
+ *
+ * The caller must specify @start, @end, @flags, and @desc
+ * (which may be IORES_DESC_NONE).
  */
 static int find_next_iomem_res(resource_size_t start, resource_size_t end,
 			       unsigned long flags, unsigned long desc,
 			       bool first_lvl, struct resource *res)
 {
 	bool siblings_only = true;
 	struct resource *p;
 
 	if (!res)
 		return -EINVAL;
 
 	if (start >= end)
 		return -EINVAL;
 
 	read_lock(&resource_lock);
 
 	for (p = iomem_resource.child; p; p = next_resource(p, siblings_only)) {
 		/* If we passed the resource we are looking for, stop */
 		if (p->start > end) {
 			p = NULL;
@@ -399,52 +401,54 @@ static int __walk_iomem_res_desc(resource_size_t start, resource_size_t end,
 				 unsigned long flags, unsigned long desc,
 				 bool first_lvl, void *arg,
 				 int (*func)(struct resource *, void *))
 {
 	struct resource res;
 	int ret = -EINVAL;
 
 	while (start < end &&
 	       !find_next_iomem_res(start, end, flags, desc, first_lvl, &res)) {
 		ret = (*func)(&res, arg);
 		if (ret)
 			break;
 
 		start = res.end + 1;
 	}
 
 	return ret;
 }
 
 /**
- * Walks through iomem resources and calls func() with matching resource
- * ranges. This walks through whole tree and not just first level children.
- * All the memory ranges which overlap start,end and also match flags and
- * desc are valid candidates.
- *
+ * walk_iomem_res_desc - Walks through iomem resources and calls func()
+ *			 with matching resource ranges.
+ * *
  * @desc: I/O resource descriptor. Use IORES_DESC_NONE to skip @desc check.
  * @flags: I/O resource flags
  * @start: start addr
  * @end: end addr
  * @arg: function argument for the callback @func
  * @func: callback function that is called for each qualifying resource area
  *
+ * This walks through whole tree and not just first level children.
+ * All the memory ranges which overlap start,end and also match flags and
+ * desc are valid candidates.
+ *
  * NOTE: For a new descriptor search, define a new IORES_DESC in
  * <linux/ioport.h> and set it in 'desc' of a target resource entry.
  */
 int walk_iomem_res_desc(unsigned long desc, unsigned long flags, u64 start,
 		u64 end, void *arg, int (*func)(struct resource *, void *))
 {
 	return __walk_iomem_res_desc(start, end, flags, desc, false, arg, func);
 }
 EXPORT_SYMBOL_GPL(walk_iomem_res_desc);
 
 /*
  * This function calls the @func callback against all memory ranges of type
  * System RAM which are marked as IORESOURCE_SYSTEM_RAM and IORESOUCE_BUSY.
  * Now, this function is only for System RAM, it deals with full ranges and
  * not PFNs. If resources are not PFN-aligned, dealing with PFNs can truncate
  * ranges.
  */
 int walk_system_ram_res(u64 start, u64 end, void *arg,
 			int (*func)(struct resource *, void *))
 {
@@ -1355,43 +1359,43 @@ void release_mem_region_adjustable(resource_size_t start, resource_size_t size)
 		}
 
 		break;
 	}
 
 	write_unlock(&resource_lock);
 	free_resource(new_res);
 }
 #endif	/* CONFIG_MEMORY_HOTREMOVE */
 
 #ifdef CONFIG_MEMORY_HOTPLUG
 static bool system_ram_resources_mergeable(struct resource *r1,
 					   struct resource *r2)
 {
 	/* We assume either r1 or r2 is IORESOURCE_SYSRAM_MERGEABLE. */
 	return r1->flags == r2->flags && r1->end + 1 == r2->start &&
 	       r1->name == r2->name && r1->desc == r2->desc &&
 	       !r1->child && !r2->child;
 }
 
-/*
+/**
  * merge_system_ram_resource - mark the System RAM resource mergeable and try to
- * merge it with adjacent, mergeable resources
+ * 	merge it with adjacent, mergeable resources
  * @res: resource descriptor
  *
  * This interface is intended for memory hotplug, whereby lots of contiguous
  * system ram resources are added (e.g., via add_memory*()) by a driver, and
  * the actual resource boundaries are not of interest (e.g., it might be
  * relevant for DIMMs). Only resources that are marked mergeable, that have the
  * same parent, and that don't have any children are considered. All mergeable
  * resources must be immutable during the request.
  *
  * Note:
  * - The caller has to make sure that no pointers to resources that are
  *   marked mergeable are used anymore after this call - the resource might
  *   be freed and the pointer might be stale!
  * - release_mem_region_adjustable() will split on demand on memory hotunplug
  */
 void merge_system_ram_resource(struct resource *res)
 {
 	const unsigned long flags = IORESOURCE_SYSTEM_RAM | IORESOURCE_BUSY;
 	struct resource *cur;
 
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 24/27] shed: fix kernel-doc markup
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (22 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 23/27] resource: fix kernel-doc markups Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 12:34   ` Vincent Guittot
  2020-11-16 10:18 ` [PATCH v4 25/27] mm: fix kernel-doc markups Mauro Carvalho Chehab
                   ` (3 subsequent siblings)
  27 siblings, 1 reply; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Ingo Molnar, Juri Lelli, Peter Zijlstra, Vincent Guittot
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	Ben Segall, Daniel Bristot de Oliveira, Dietmar Eggemann,
	Mel Gorman, Steven Rostedt, linux-kernel

Kernel-doc requires that a kernel-doc markup to be immediatly
below the function prototype, as otherwise it will rename it.
So, move sys_sched_yield() markup to the right place.

Also fix the cpu_util() markup: Kernel-doc markups
should use this format:
        identifier - description

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 kernel/sched/core.c | 16 ++++++++--------
 kernel/sched/fair.c |  2 +-
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/kernel/sched/core.c b/kernel/sched/core.c
index 02076e6d3792..9d41378ae8f3 100644
--- a/kernel/sched/core.c
+++ b/kernel/sched/core.c
@@ -6560,65 +6560,65 @@ SYSCALL_DEFINE3(sched_getaffinity, pid_t, pid, unsigned int, len,
 	if (len & (sizeof(unsigned long)-1))
 		return -EINVAL;
 
 	if (!alloc_cpumask_var(&mask, GFP_KERNEL))
 		return -ENOMEM;
 
 	ret = sched_getaffinity(pid, mask);
 	if (ret == 0) {
 		unsigned int retlen = min(len, cpumask_size());
 
 		if (copy_to_user(user_mask_ptr, mask, retlen))
 			ret = -EFAULT;
 		else
 			ret = retlen;
 	}
 	free_cpumask_var(mask);
 
 	return ret;
 }
 
-/**
- * sys_sched_yield - yield the current processor to other threads.
- *
- * This function yields the current CPU to other tasks. If there are no
- * other threads running on this CPU then this function will return.
- *
- * Return: 0.
- */
 static void do_sched_yield(void)
 {
 	struct rq_flags rf;
 	struct rq *rq;
 
 	rq = this_rq_lock_irq(&rf);
 
 	schedstat_inc(rq->yld_count);
 	current->sched_class->yield_task(rq);
 
 	preempt_disable();
 	rq_unlock_irq(rq, &rf);
 	sched_preempt_enable_no_resched();
 
 	schedule();
 }
 
+/**
+ * sys_sched_yield - yield the current processor to other threads.
+ *
+ * This function yields the current CPU to other tasks. If there are no
+ * other threads running on this CPU then this function will return.
+ *
+ * Return: 0.
+ */
 SYSCALL_DEFINE0(sched_yield)
 {
 	do_sched_yield();
 	return 0;
 }
 
 #ifndef CONFIG_PREEMPTION
 int __sched _cond_resched(void)
 {
 	if (should_resched(0)) {
 		preempt_schedule_common();
 		return 1;
 	}
 	rcu_all_qs();
 	return 0;
 }
 EXPORT_SYMBOL(_cond_resched);
 #endif
 
 /*
diff --git a/kernel/sched/fair.c b/kernel/sched/fair.c
index 27536f37ba1a..cb7cd7d8a28f 100644
--- a/kernel/sched/fair.c
+++ b/kernel/sched/fair.c
@@ -6310,41 +6310,41 @@ static int select_idle_sibling(struct task_struct *p, int prev, int target)
 	sd = rcu_dereference(per_cpu(sd_llc, target));
 	if (!sd)
 		return target;
 
 	i = select_idle_core(p, sd, target);
 	if ((unsigned)i < nr_cpumask_bits)
 		return i;
 
 	i = select_idle_cpu(p, sd, target);
 	if ((unsigned)i < nr_cpumask_bits)
 		return i;
 
 	i = select_idle_smt(p, sd, target);
 	if ((unsigned)i < nr_cpumask_bits)
 		return i;
 
 	return target;
 }
 
 /**
- * Amount of capacity of a CPU that is (estimated to be) used by CFS tasks
+ * cpu_util - Estimates the amount of capacity of a CPU used by CFS tasks.
  * @cpu: the CPU to get the utilization of
  *
  * The unit of the return value must be the one of capacity so we can compare
  * the utilization with the capacity of the CPU that is available for CFS task
  * (ie cpu_capacity).
  *
  * cfs_rq.avg.util_avg is the sum of running time of runnable tasks plus the
  * recent utilization of currently non-runnable tasks on a CPU. It represents
  * the amount of utilization of a CPU in the range [0..capacity_orig] where
  * capacity_orig is the cpu_capacity available at the highest frequency
  * (arch_scale_freq_capacity()).
  * The utilization of a CPU converges towards a sum equal to or less than the
  * current capacity (capacity_curr <= capacity_orig) of the CPU because it is
  * the running time on this CPU scaled by capacity_curr.
  *
  * The estimated utilization of a CPU is defined to be the maximum between its
  * cfs_rq.avg.util_avg and the sum of the estimated utilization of the tasks
  * currently RUNNABLE on that CPU.
  * This allows to properly represent the expected utilization of a CPU which
  * has just got a big task running since a long sleep period. At the same time
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 25/27] mm: fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (23 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 24/27] shed: fix kernel-doc markup Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 26/27] selftests: kselftest_harness.h: partially " Mauro Carvalho Chehab
                   ` (2 subsequent siblings)
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Andrew Morton
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	linux-kernel, linux-mm, Mattew Wilcox

Kernel-doc markups should use this format:
        identifier - description

Fix some issues on mm files:

1) The definition for get_user_pages_locked() doesn't follow
   it. Also, it expects a short descrpition at the header,
   followed by a long one, after the parameters. Fix it.

2) Kernel-doc requires that a kernel-doc markup to be immediatly
   below the function prototype, as otherwise it will rename it.
   So, move get_pfnblock_flags_mask() description to the right
   place.

3) Make invalidate_mapping_pagevec() to also follow the
   expected kernel-doc format.

While here, fix a few minor English syntax issues, as suggested
by Matthew:
	will used -> will be used
	similar with -> similar to

Suggested-by: Mattew Wilcox <willy@infradead.org> # English fixes
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 mm/gup.c        | 24 +++++++++++++-----------
 mm/page_alloc.c | 16 ++++++++--------
 mm/truncate.c   | 10 ++++++++--
 3 files changed, 29 insertions(+), 21 deletions(-)

diff --git a/mm/gup.c b/mm/gup.c
index 49c4eabca271..f3751bf28326 100644
--- a/mm/gup.c
+++ b/mm/gup.c
@@ -1924,66 +1924,68 @@ static long __get_user_pages_remote(struct mm_struct *mm,
  *              Or NULL if the caller does not require them.
  *
  * This is the same as get_user_pages_remote(), just with a less-flexible
  * calling convention where we assume that the mm being operated on belongs to
  * the current task, and doesn't allow passing of a locked parameter.  We also
  * obviously don't pass FOLL_REMOTE in here.
  */
 long get_user_pages(unsigned long start, unsigned long nr_pages,
 		unsigned int gup_flags, struct page **pages,
 		struct vm_area_struct **vmas)
 {
 	if (!is_valid_gup_flags(gup_flags))
 		return -EINVAL;
 
 	return __gup_longterm_locked(current->mm, start, nr_pages,
 				     pages, vmas, gup_flags | FOLL_TOUCH);
 }
 EXPORT_SYMBOL(get_user_pages);
 
 /**
- * get_user_pages_locked() is suitable to replace the form:
+ * get_user_pages_locked() - variant of get_user_pages()
+ *
+ * @start:      starting user address
+ * @nr_pages:   number of pages from start to pin
+ * @gup_flags:  flags modifying lookup behaviour
+ * @pages:      array that receives pointers to the pages pinned.
+ *              Should be at least nr_pages long. Or NULL, if caller
+ *              only intends to ensure the pages are faulted in.
+ * @locked:     pointer to lock flag indicating whether lock is held and
+ *              subsequently whether VM_FAULT_RETRY functionality can be
+ *              utilised. Lock must initially be held.
+ *
+ * It is suitable to replace the form:
  *
  *      mmap_read_lock(mm);
  *      do_something()
  *      get_user_pages(mm, ..., pages, NULL);
  *      mmap_read_unlock(mm);
  *
  *  to:
  *
  *      int locked = 1;
  *      mmap_read_lock(mm);
  *      do_something()
  *      get_user_pages_locked(mm, ..., pages, &locked);
  *      if (locked)
  *          mmap_read_unlock(mm);
  *
- * @start:      starting user address
- * @nr_pages:   number of pages from start to pin
- * @gup_flags:  flags modifying lookup behaviour
- * @pages:      array that receives pointers to the pages pinned.
- *              Should be at least nr_pages long. Or NULL, if caller
- *              only intends to ensure the pages are faulted in.
- * @locked:     pointer to lock flag indicating whether lock is held and
- *              subsequently whether VM_FAULT_RETRY functionality can be
- *              utilised. Lock must initially be held.
- *
  * We can leverage the VM_FAULT_RETRY functionality in the page fault
  * paths better by using either get_user_pages_locked() or
  * get_user_pages_unlocked().
  *
  */
 long get_user_pages_locked(unsigned long start, unsigned long nr_pages,
 			   unsigned int gup_flags, struct page **pages,
 			   int *locked)
 {
 	/*
 	 * FIXME: Current FOLL_LONGTERM behavior is incompatible with
 	 * FAULT_FLAG_ALLOW_RETRY because of the FS DAX check requirement on
 	 * vmas.  As there are no users of this flag in this call we simply
 	 * disallow this option for now.
 	 */
 	if (WARN_ON_ONCE(gup_flags & FOLL_LONGTERM))
 		return -EINVAL;
 	/*
 	 * FOLL_PIN must only be set internally by the pin_user_pages*() APIs,
 	 * never directly by the caller, so enforce that:
diff --git a/mm/page_alloc.c b/mm/page_alloc.c
index 63d8d8b72c10..7e4d1e4bdee9 100644
--- a/mm/page_alloc.c
+++ b/mm/page_alloc.c
@@ -478,66 +478,66 @@ static inline bool defer_init(int nid, unsigned long pfn, unsigned long end_pfn)
 static inline unsigned long *get_pageblock_bitmap(struct page *page,
 							unsigned long pfn)
 {
 #ifdef CONFIG_SPARSEMEM
 	return section_to_usemap(__pfn_to_section(pfn));
 #else
 	return page_zone(page)->pageblock_flags;
 #endif /* CONFIG_SPARSEMEM */
 }
 
 static inline int pfn_to_bitidx(struct page *page, unsigned long pfn)
 {
 #ifdef CONFIG_SPARSEMEM
 	pfn &= (PAGES_PER_SECTION-1);
 #else
 	pfn = pfn - round_down(page_zone(page)->zone_start_pfn, pageblock_nr_pages);
 #endif /* CONFIG_SPARSEMEM */
 	return (pfn >> pageblock_order) * NR_PAGEBLOCK_BITS;
 }
 
-/**
- * get_pfnblock_flags_mask - Return the requested group of flags for the pageblock_nr_pages block of pages
- * @page: The page within the block of interest
- * @pfn: The target page frame number
- * @mask: mask of bits that the caller is interested in
- *
- * Return: pageblock_bits flags
- */
 static __always_inline
 unsigned long __get_pfnblock_flags_mask(struct page *page,
 					unsigned long pfn,
 					unsigned long mask)
 {
 	unsigned long *bitmap;
 	unsigned long bitidx, word_bitidx;
 	unsigned long word;
 
 	bitmap = get_pageblock_bitmap(page, pfn);
 	bitidx = pfn_to_bitidx(page, pfn);
 	word_bitidx = bitidx / BITS_PER_LONG;
 	bitidx &= (BITS_PER_LONG-1);
 
 	word = bitmap[word_bitidx];
 	return (word >> bitidx) & mask;
 }
 
+/**
+ * get_pfnblock_flags_mask - Return the requested group of flags for the pageblock_nr_pages block of pages
+ * @page: The page within the block of interest
+ * @pfn: The target page frame number
+ * @mask: mask of bits that the caller is interested in
+ *
+ * Return: pageblock_bits flags
+ */
 unsigned long get_pfnblock_flags_mask(struct page *page, unsigned long pfn,
 					unsigned long mask)
 {
 	return __get_pfnblock_flags_mask(page, pfn, mask);
 }
 
 static __always_inline int get_pfnblock_migratetype(struct page *page, unsigned long pfn)
 {
 	return __get_pfnblock_flags_mask(page, pfn, MIGRATETYPE_MASK);
 }
 
 /**
  * set_pfnblock_flags_mask - Set the requested group of flags for a pageblock_nr_pages block of pages
  * @page: The page within the block of interest
  * @flags: The flags to set
  * @pfn: The target page frame number
  * @mask: mask of bits that the caller is interested in
  */
 void set_pfnblock_flags_mask(struct page *page, unsigned long flags,
 					unsigned long pfn,
diff --git a/mm/truncate.c b/mm/truncate.c
index 960edf5803ca..604eaabc6d06 100644
--- a/mm/truncate.c
+++ b/mm/truncate.c
@@ -620,43 +620,49 @@ static unsigned long __invalidate_mapping_pages(struct address_space *mapping,
  * @start: the offset 'from' which to invalidate
  * @end: the offset 'to' which to invalidate (inclusive)
  *
  * This function only removes the unlocked pages, if you want to
  * remove all the pages of one inode, you must call truncate_inode_pages.
  *
  * invalidate_mapping_pages() will not block on IO activity. It will not
  * invalidate pages which are dirty, locked, under writeback or mapped into
  * pagetables.
  *
  * Return: the number of the pages that were invalidated
  */
 unsigned long invalidate_mapping_pages(struct address_space *mapping,
 		pgoff_t start, pgoff_t end)
 {
 	return __invalidate_mapping_pages(mapping, start, end, NULL);
 }
 EXPORT_SYMBOL(invalidate_mapping_pages);
 
 /**
- * This helper is similar with the above one, except that it accounts for pages
- * that are likely on a pagevec and count them in @nr_pagevec, which will used by
+ * invalidate_mapping_pagevec - This helper is similar to
+ * invalidate_mapping_pages(), except that it accounts for pages that are
+ * likely on a pagevec and count them in @nr_pagevec, which will be used by
  * the caller.
+ *
+ * @mapping: the address_space which holds the pages to invalidate
+ * @start: the offset 'from' which to invalidate
+ * @end: the offset 'to' which to invalidate (inclusive)
+ *
  */
 void invalidate_mapping_pagevec(struct address_space *mapping,
 		pgoff_t start, pgoff_t end, unsigned long *nr_pagevec)
 {
 	__invalidate_mapping_pages(mapping, start, end, nr_pagevec);
 }
 
 /*
  * This is like invalidate_complete_page(), except it ignores the page's
  * refcount.  We do this because invalidate_inode_pages2() needs stronger
  * invalidation guarantees, and cannot afford to leave pages behind because
  * shrink_page_list() has a temp ref on them, or because they're transiently
  * sitting in the lru_cache_add() pagevecs.
  */
 static int
 invalidate_complete_page2(struct address_space *mapping, struct page *page)
 {
 	unsigned long flags;
 
 	if (page->mapping != mapping)
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 26/27] selftests: kselftest_harness.h: partially fix kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (24 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 25/27] mm: fix kernel-doc markups Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 10:18 ` [PATCH v4 27/27] scripts: kernel-doc: validate kernel-doc markup with the actual names Mauro Carvalho Chehab
  2020-11-17 22:19 ` [PATCH v4 00/27]Fix several bad kernel-doc markups Jakub Kicinski
  27 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Shuah Khan
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
	Andy Lutomirski, Kees Cook, Will Drewry, linux-kernel,
	linux-kselftest

The kernel-doc markups on this file are weird: they don't
follow what's specified at:

	Documentation/doc-guide/kernel-doc.rst

In particular, markups should use this format:
        identifier - description

and not this:
	identifier(args)

The way the definitions are inside this file cause the
parser to completely miss the identifier name of each
function.

This prevents improving the script to do some needed validation
tests.

Address this part. Yet, furter changes are needed in order
for it to fully follow the specs.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/testing/selftests/kselftest_harness.h | 22 ++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/tools/testing/selftests/kselftest_harness.h b/tools/testing/selftests/kselftest_harness.h
index edce85420d19..99920466076a 100644
--- a/tools/testing/selftests/kselftest_harness.h
+++ b/tools/testing/selftests/kselftest_harness.h
@@ -62,301 +62,301 @@
 #include <string.h>
 #include <sys/mman.h>
 #include <sys/types.h>
 #include <sys/wait.h>
 #include <unistd.h>
 
 #include "kselftest.h"
 
 #define TEST_TIMEOUT_DEFAULT 30
 
 /* Utilities exposed to the test definitions */
 #ifndef TH_LOG_STREAM
 #  define TH_LOG_STREAM stderr
 #endif
 
 #ifndef TH_LOG_ENABLED
 #  define TH_LOG_ENABLED 1
 #endif
 
 /**
- * TH_LOG(fmt, ...)
+ * TH_LOG()
  *
  * @fmt: format string
  * @...: optional arguments
  *
  * .. code-block:: c
  *
  *     TH_LOG(format, ...)
  *
  * Optional debug logging function available for use in tests.
  * Logging may be enabled or disabled by defining TH_LOG_ENABLED.
  * E.g., #define TH_LOG_ENABLED 1
  *
  * If no definition is provided, logging is enabled by default.
  *
  * If there is no way to print an error message for the process running the
  * test (e.g. not allowed to write to stderr), it is still possible to get the
  * ASSERT_* number for which the test failed.  This behavior can be enabled by
  * writing `_metadata->no_print = true;` before the check sequence that is
  * unable to print.  When an error occur, instead of printing an error message
  * and calling `abort(3)`, the test process call `_exit(2)` with the assert
  * number as argument, which is then printed by the parent process.
  */
 #define TH_LOG(fmt, ...) do { \
 	if (TH_LOG_ENABLED) \
 		__TH_LOG(fmt, ##__VA_ARGS__); \
 } while (0)
 
 /* Unconditional logger for internal use. */
 #define __TH_LOG(fmt, ...) \
 		fprintf(TH_LOG_STREAM, "# %s:%d:%s:" fmt "\n", \
 			__FILE__, __LINE__, _metadata->name, ##__VA_ARGS__)
 
 /**
- * SKIP(statement, fmt, ...)
+ * SKIP()
  *
  * @statement: statement to run after reporting SKIP
  * @fmt: format string
  * @...: optional arguments
  *
  * This forces a "pass" after reporting why something is being skipped
  * and runs "statement", which is usually "return" or "goto skip".
  */
 #define SKIP(statement, fmt, ...) do { \
 	snprintf(_metadata->results->reason, \
 		 sizeof(_metadata->results->reason), fmt, ##__VA_ARGS__); \
 	if (TH_LOG_ENABLED) { \
 		fprintf(TH_LOG_STREAM, "#      SKIP      %s\n", \
 			_metadata->results->reason); \
 	} \
 	_metadata->passed = 1; \
 	_metadata->skip = 1; \
 	_metadata->trigger = 0; \
 	statement; \
 } while (0)
 
 /**
- * TEST(test_name) - Defines the test function and creates the registration
+ * TEST() - Defines the test function and creates the registration
  * stub
  *
  * @test_name: test name
  *
  * .. code-block:: c
  *
  *     TEST(name) { implementation }
  *
  * Defines a test by name.
  * Names must be unique and tests must not be run in parallel.  The
  * implementation containing block is a function and scoping should be treated
  * as such.  Returning early may be performed with a bare "return;" statement.
  *
  * EXPECT_* and ASSERT_* are valid in a TEST() { } context.
  */
 #define TEST(test_name) __TEST_IMPL(test_name, -1)
 
 /**
- * TEST_SIGNAL(test_name, signal)
+ * TEST_SIGNAL()
  *
  * @test_name: test name
  * @signal: signal number
  *
  * .. code-block:: c
  *
  *     TEST_SIGNAL(name, signal) { implementation }
  *
  * Defines a test by name and the expected term signal.
  * Names must be unique and tests must not be run in parallel.  The
  * implementation containing block is a function and scoping should be treated
  * as such.  Returning early may be performed with a bare "return;" statement.
  *
  * EXPECT_* and ASSERT_* are valid in a TEST() { } context.
  */
 #define TEST_SIGNAL(test_name, signal) __TEST_IMPL(test_name, signal)
 
 #define __TEST_IMPL(test_name, _signal) \
 	static void test_name(struct __test_metadata *_metadata); \
 	static inline void wrapper_##test_name( \
 		struct __test_metadata *_metadata, \
 		struct __fixture_variant_metadata *variant) \
 	{ \
 		test_name(_metadata); \
 	} \
 	static struct __test_metadata _##test_name##_object = \
 		{ .name = #test_name, \
 		  .fn = &wrapper_##test_name, \
 		  .fixture = &_fixture_global, \
 		  .termsig = _signal, \
 		  .timeout = TEST_TIMEOUT_DEFAULT, }; \
 	static void __attribute__((constructor)) _register_##test_name(void) \
 	{ \
 		__register_test(&_##test_name##_object); \
 	} \
 	static void test_name( \
 		struct __test_metadata __attribute__((unused)) *_metadata)
 
 /**
- * FIXTURE_DATA(datatype_name) - Wraps the struct name so we have one less
+ * FIXTURE_DATA() - Wraps the struct name so we have one less
  * argument to pass around
  *
  * @datatype_name: datatype name
  *
  * .. code-block:: c
  *
  *     FIXTURE_DATA(datatype_name)
  *
  * Almost always, you want just FIXTURE() instead (see below).
  * This call may be used when the type of the fixture data
  * is needed.  In general, this should not be needed unless
  * the *self* is being passed to a helper directly.
  */
 #define FIXTURE_DATA(datatype_name) struct _test_data_##datatype_name
 
 /**
- * FIXTURE(fixture_name) - Called once per fixture to setup the data and
+ * FIXTURE() - Called once per fixture to setup the data and
  * register
  *
  * @fixture_name: fixture name
  *
  * .. code-block:: c
  *
  *     FIXTURE(fixture_name) {
  *       type property1;
  *       ...
  *     };
  *
  * Defines the data provided to TEST_F()-defined tests as *self*.  It should be
  * populated and cleaned up using FIXTURE_SETUP() and FIXTURE_TEARDOWN().
  */
 #define FIXTURE(fixture_name) \
 	FIXTURE_VARIANT(fixture_name); \
 	static struct __fixture_metadata _##fixture_name##_fixture_object = \
 		{ .name =  #fixture_name, }; \
 	static void __attribute__((constructor)) \
 	_register_##fixture_name##_data(void) \
 	{ \
 		__register_fixture(&_##fixture_name##_fixture_object); \
 	} \
 	FIXTURE_DATA(fixture_name)
 
 /**
- * FIXTURE_SETUP(fixture_name) - Prepares the setup function for the fixture.
+ * FIXTURE_SETUP() - Prepares the setup function for the fixture.
  * *_metadata* is included so that EXPECT_* and ASSERT_* work correctly.
  *
  * @fixture_name: fixture name
  *
  * .. code-block:: c
  *
  *     FIXTURE_SETUP(fixture_name) { implementation }
  *
  * Populates the required "setup" function for a fixture.  An instance of the
  * datatype defined with FIXTURE_DATA() will be exposed as *self* for the
  * implementation.
  *
  * ASSERT_* are valid for use in this context and will prempt the execution
  * of any dependent fixture tests.
  *
  * A bare "return;" statement may be used to return early.
  */
 #define FIXTURE_SETUP(fixture_name) \
 	void fixture_name##_setup( \
 		struct __test_metadata __attribute__((unused)) *_metadata, \
 		FIXTURE_DATA(fixture_name) __attribute__((unused)) *self, \
 		const FIXTURE_VARIANT(fixture_name) \
 			__attribute__((unused)) *variant)
 
 /**
- * FIXTURE_TEARDOWN(fixture_name)
+ * FIXTURE_TEARDOWN()
  * *_metadata* is included so that EXPECT_* and ASSERT_* work correctly.
  *
  * @fixture_name: fixture name
  *
  * .. code-block:: c
  *
  *     FIXTURE_TEARDOWN(fixture_name) { implementation }
  *
  * Populates the required "teardown" function for a fixture.  An instance of the
  * datatype defined with FIXTURE_DATA() will be exposed as *self* for the
  * implementation to clean up.
  *
  * A bare "return;" statement may be used to return early.
  */
 #define FIXTURE_TEARDOWN(fixture_name) \
 	void fixture_name##_teardown( \
 		struct __test_metadata __attribute__((unused)) *_metadata, \
 		FIXTURE_DATA(fixture_name) __attribute__((unused)) *self)
 
 /**
- * FIXTURE_VARIANT(fixture_name) - Optionally called once per fixture
+ * FIXTURE_VARIANT() - Optionally called once per fixture
  * to declare fixture variant
  *
  * @fixture_name: fixture name
  *
  * .. code-block:: c
  *
  *     FIXTURE_VARIANT(fixture_name) {
  *       type property1;
  *       ...
  *     };
  *
  * Defines type of constant parameters provided to FIXTURE_SETUP() and TEST_F()
  * as *variant*. Variants allow the same tests to be run with different
  * arguments.
  */
 #define FIXTURE_VARIANT(fixture_name) struct _fixture_variant_##fixture_name
 
 /**
- * FIXTURE_VARIANT_ADD(fixture_name, variant_name) - Called once per fixture
+ * FIXTURE_VARIANT_ADD() - Called once per fixture
  * variant to setup and register the data
  *
  * @fixture_name: fixture name
  * @variant_name: name of the parameter set
  *
  * .. code-block:: c
  *
  *     FIXTURE_VARIANT_ADD(fixture_name, variant_name) {
  *       .property1 = val1,
  *       ...
  *     };
  *
  * Defines a variant of the test fixture, provided to FIXTURE_SETUP() and
  * TEST_F() as *variant*. Tests of each fixture will be run once for each
  * variant.
  */
 #define FIXTURE_VARIANT_ADD(fixture_name, variant_name) \
 	extern FIXTURE_VARIANT(fixture_name) \
 		_##fixture_name##_##variant_name##_variant; \
 	static struct __fixture_variant_metadata \
 		_##fixture_name##_##variant_name##_object = \
 		{ .name = #variant_name, \
 		  .data = &_##fixture_name##_##variant_name##_variant}; \
 	static void __attribute__((constructor)) \
 		_register_##fixture_name##_##variant_name(void) \
 	{ \
 		__register_fixture_variant(&_##fixture_name##_fixture_object, \
 			&_##fixture_name##_##variant_name##_object);	\
 	} \
 	FIXTURE_VARIANT(fixture_name) \
 		_##fixture_name##_##variant_name##_variant =
 
 /**
- * TEST_F(fixture_name, test_name) - Emits test registration and helpers for
+ * TEST_F() - Emits test registration and helpers for
  * fixture-based test cases
  *
  * @fixture_name: fixture name
  * @test_name: test name
  *
  * .. code-block:: c
  *
  *     TEST_F(fixture, name) { implementation }
  *
  * Defines a test that depends on a fixture (e.g., is part of a test case).
  * Very similar to TEST() except that *self* is the setup instance of fixture's
  * datatype exposed for use by the implementation.
  *
  * Warning: use of ASSERT_* here will skip TEARDOWN.
  */
 /* TODO(wad) register fixtures on dedicated test lists. */
 #define TEST_F(fixture_name, test_name) \
 	__TEST_F_IMPL(fixture_name, test_name, -1, TEST_TIMEOUT_DEFAULT)
 
 #define TEST_F_SIGNAL(fixture_name, test_name, signal) \
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* [PATCH v4 27/27] scripts: kernel-doc: validate kernel-doc markup with the actual names
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (25 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 26/27] selftests: kselftest_harness.h: partially " Mauro Carvalho Chehab
@ 2020-11-16 10:18 ` Mauro Carvalho Chehab
  2020-11-16 15:06   ` kernel test robot
                     ` (2 more replies)
  2020-11-17 22:19 ` [PATCH v4 00/27]Fix several bad kernel-doc markups Jakub Kicinski
  27 siblings, 3 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 10:18 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Mauro Carvalho Chehab, Linux Doc Mailing List, linux-kernel

Kernel-doc currently expects that the kernel-doc markup to come
just before the function/enum/struct/union/typedef prototype.

Yet, if it find things like:

	/**
	 * refcount_add - add a value to a refcount
	 * @i: the value to add to the refcount
	 * @r: the refcount
	 */
	static inline void __refcount_add(int i, refcount_t *r, int *oldp);
	static inline void refcount_add(int i, refcount_t *r);

Kernel-doc will do the wrong thing:

	foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add'
	.. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp)

	   add a value to a refcount

	**Parameters**

	``int i``
	  the value to add to the refcount

	``refcount_t *r``
	  the refcount

	``int *oldp``
	  *undescribed*

Basically, it will document "__refcount_add" with the kernel-doc
markup for refcount_add.

If both functions have the same arguments, this won't even
produce any warning!

Add a logic to check if the kernel-doc identifier matches the actual
name of the C function or data structure that will be documented.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 62 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 46 insertions(+), 16 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9b6ddeb097e9..919acae23fad 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -365,40 +365,43 @@ use constant {
 my $state;
 my $in_doc_sect;
 my $leading_space;
 
 # Inline documentation state
 use constant {
     STATE_INLINE_NA     => 0, # not applicable ($state != STATE_INLINE)
     STATE_INLINE_NAME   => 1, # looking for member name (@foo:)
     STATE_INLINE_TEXT   => 2, # looking for member documentation
     STATE_INLINE_END    => 3, # done
     STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
                               # Spit a warning as it's not
                               # proper kernel-doc and ignore the rest.
 };
 my $inline_doc_state;
 
 #declaration types: can be
 # 'function', 'struct', 'union', 'enum', 'typedef'
 my $decl_type;
 
+# Name of the kernel-doc identifier for non-DOC markups
+my $identifier;
+
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
 my $doc_com_body = '\s*\* ?';
 my $doc_decl = $doc_com . '(\w+)';
 # @params and a strictly limited set of supported section names
 my $doc_sect = $doc_com .
     '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
 my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
 my $doc_inline_end = '^\s*\*/\s*$';
 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
 
 my %parameterdescs;
 my %parameterdesc_start_lines;
 my @parameterlist;
 my %sections;
@@ -1186,40 +1189,45 @@ sub output_blockhead {
 sub dump_declaration($$) {
     no strict 'refs';
     my ($prototype, $file) = @_;
     my $func = "dump_" . $decl_type;
     &$func(@_);
 }
 
 sub dump_union($$) {
     dump_struct(@_);
 }
 
 sub dump_struct($$) {
     my $x = shift;
     my $file = shift;
 
     if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
 	my $decl_type = $1;
 	$declaration_name = $2;
 	my $members = $3;
 
+	if ($identifier ne $declaration_name) {
+	    print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
+	    return;
+	}
+
 	# ignore members marked private:
 	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
 	$members =~ s/\/\*\s*private:.*//gosi;
 	# strip comments:
 	$members =~ s/\/\*.*?\*\///gos;
 	# strip attributes
 	$members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi;
 	$members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
 	$members =~ s/\s*__packed\s*/ /gos;
 	$members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
 	$members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
 	$members =~ s/\s*____cacheline_aligned/ /gos;
 
 	# replace DECLARE_BITMAP
 	$members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos;
 	$members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
 	# replace DECLARE_HASHTABLE
 	$members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
 	# replace DECLARE_KFIFO
 	$members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
@@ -1374,40 +1382,45 @@ sub show_warnings($$) {
 
 sub dump_enum($$) {
     my $x = shift;
     my $file = shift;
     my $members;
 
 
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
     # strip #define macros inside enums
     $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
 
     if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
 	$declaration_name = $2;
 	$members = $1;
     } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
 	$declaration_name = $1;
 	$members = $2;
     }
 
     if ($members) {
+	if ($identifier ne $declaration_name) {
+	    print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
+	    return;
+	}
+
 	my %_members;
 
 	$members =~ s/\s+$//;
 
 	foreach my $arg (split ',', $members) {
 	    $arg =~ s/^\s*(\w+).*/$1/;
 	    push @parameterlist, $arg;
 	    if (!$parameterdescs{$arg}) {
 		$parameterdescs{$arg} = $undescribed;
 	        if (show_warnings("enum", $declaration_name)) {
 			print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
 		}
 	    }
 	    $_members{$arg} = 1;
 	}
 
 	while (my ($k, $v) = each %parameterdescs) {
 	    if (!exists($_members{$k})) {
 	        if (show_warnings("enum", $declaration_name)) {
 		     print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
@@ -1434,66 +1447,76 @@ sub dump_enum($$) {
 my $typedef_type = qr { ((?:\s+[\w\*]+){1,8})\s* }x;
 my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
 my $typedef_args = qr { \s*\((.*)\); }x;
 
 my $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x;
 my $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x;
 
 sub dump_typedef($$) {
     my $x = shift;
     my $file = shift;
 
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
 
     # Parse function typedef prototypes
     if ($x =~ $typedef1 || $x =~ $typedef2) {
 	$return_type = $1;
 	$declaration_name = $2;
 	my $args = $3;
 	$return_type =~ s/^\s+//;
 
+	if ($identifier ne $declaration_name) {
+	    print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+	    return;
+	}
+
 	create_parameterlist($args, ',', $file, $declaration_name);
 
 	output_declaration($declaration_name,
 			   'function',
 			   {'function' => $declaration_name,
 			    'typedef' => 1,
 			    'module' => $modulename,
 			    'functiontype' => $return_type,
 			    'parameterlist' => \@parameterlist,
 			    'parameterdescs' => \%parameterdescs,
 			    'parametertypes' => \%parametertypes,
 			    'sectionlist' => \@sectionlist,
 			    'sections' => \%sections,
 			    'purpose' => $declaration_purpose
 			   });
 	return;
     }
 
     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
 	$x =~ s/\(*.\)\s*;$/;/;
 	$x =~ s/\[*.\]\s*;$/;/;
     }
 
     if ($x =~ /typedef.*\s+(\w+)\s*;/) {
 	$declaration_name = $1;
 
+	if ($identifier ne $declaration_name) {
+	    print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+	    return;
+	}
+
 	output_declaration($declaration_name,
 			   'typedef',
 			   {'typedef' => $declaration_name,
 			    'module' => $modulename,
 			    'sectionlist' => \@sectionlist,
 			    'sections' => \%sections,
 			    'purpose' => $declaration_purpose
 			   });
     }
     else {
 	print STDERR "${file}:$.: error: Cannot parse typedef!\n";
 	++$errors;
     }
 }
 
 sub save_struct_actual($) {
     my $actual = shift;
 
     # strip all spaces from the actual param so that it looks like one string item
     $actual =~ s/\s*//g;
@@ -1779,40 +1802,45 @@ sub dump_function($$) {
 	$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
 	$return_type = $1;
 	$declaration_name = $2;
 	my $args = $3;
 
 	create_parameterlist($args, ',', $file, $declaration_name);
     } else {
 	print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
 	return;
     }
 
+    if ($identifier ne $declaration_name) {
+	print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
+	return;
+    }
+
     my $prms = join " ", @parameterlist;
     check_sections($file, $declaration_name, "function", $sectcheck, $prms);
 
     # This check emits a lot of warnings at the moment, because many
     # functions don't have a 'Return' doc section. So until the number
     # of warnings goes sufficiently down, the check is only performed in
     # verbose mode.
     # TODO: always perform the check.
     if ($verbose && !$noret) {
 	    check_return_section($file, $declaration_name, $return_type);
     }
 
     # The function parser can be called with a typedef parameter.
     # Handle it.
     if ($return_type =~ /typedef/) {
 	output_declaration($declaration_name,
 			   'function',
 			   {'function' => $declaration_name,
 			    'typedef' => 1,
 			    'module' => $modulename,
@@ -1861,40 +1889,41 @@ sub tracepoint_munge($) {
 	my $tracepointargs = 0;
 
 	if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
 		$tracepointname = $1;
 	}
 	if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
 		$tracepointname = $1;
 	}
 	if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
 		$tracepointname = $2;
 	}
 	$tracepointname =~ s/^\s+//; #strip leading whitespace
 	if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
 		$tracepointargs = $1;
 	}
 	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
 		print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
 			     "$prototype\n";
 	} else {
 		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
+		$identifier = "trace_$identifier";
 	}
 }
 
 sub syscall_munge() {
 	my $void = 0;
 
 	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
 ##	if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
 	if ($prototype =~ m/SYSCALL_DEFINE0/) {
 		$void = 1;
 ##		$prototype = "long sys_$1(void)";
 	}
 
 	$prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
 	if ($prototype =~ m/long (sys_.*?),/) {
 		$prototype =~ s/,/\(/;
 	} elsif ($void) {
 		$prototype =~ s/\)/\(void\)/;
 	}
 
@@ -2024,98 +2053,99 @@ sub process_export_file($) {
 }
 
 #
 # Parsers for the various processing states.
 #
 # STATE_NORMAL: looking for the /** to begin everything.
 #
 sub process_normal() {
     if (/$doc_start/o) {
 	$state = STATE_NAME;	# next line is always the function name
 	$in_doc_sect = 0;
 	$declaration_start_line = $. + 1;
     }
 }
 
 #
 # STATE_NAME: Looking for the "name - description" line
 #
 sub process_name($$) {
     my $file = shift;
-    my $identifier;
     my $descr;
 
     if (/$doc_block/o) {
 	$state = STATE_DOCBLOCK;
 	$contents = "";
 	$new_start_line = $.;
 
 	if ( $1 eq "" ) {
 	    $section = $section_intro;
 	} else {
 	    $section = $1;
 	}
-    }
-    elsif (/$doc_decl/o) {
+    } elsif (/$doc_decl/o) {
 	$identifier = $1;
-	if (/\s*([\w\s]+?)(\(\))?\s*-/) {
+	if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
 	    $identifier = $1;
 	}
+	if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
+	    $decl_type = $1;
+	    $identifier = $2;
+	} else {
+	    $decl_type = 'function';
+	    $identifier =~ s/^define\s+//;
+	}
+	$identifier =~ s/\s+$//;
 
 	$state = STATE_BODY;
 	# if there's no @param blocks need to set up default section
 	# here
 	$contents = "";
 	$section = $section_default;
 	$new_start_line = $. + 1;
-	if (/-(.*)/) {
+	if (/[-:](.*)/) {
 	    # strip leading/trailing/multiple spaces
 	    $descr= $1;
 	    $descr =~ s/^\s*//;
 	    $descr =~ s/\s*$//;
 	    $descr =~ s/\s+/ /g;
 	    $declaration_purpose = $descr;
 	    $state = STATE_BODY_MAYBE;
 	} else {
 	    $declaration_purpose = "";
 	}
 
 	if (($declaration_purpose eq "") && $verbose) {
 	    print STDERR "${file}:$.: warning: missing initial short description on line:\n";
 	    print STDERR $_;
 	    ++$warnings;
 	}
 
-	if ($identifier =~ m/^struct\b/) {
-	    $decl_type = 'struct';
-	} elsif ($identifier =~ m/^union\b/) {
-	    $decl_type = 'union';
-	} elsif ($identifier =~ m/^enum\b/) {
-	    $decl_type = 'enum';
-	} elsif ($identifier =~ m/^typedef\b/) {
-	    $decl_type = 'typedef';
-	} else {
-	    $decl_type = 'function';
+	if ($identifier eq "") {
+	    print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
+	    print STDERR $_;
+	    ++$warnings;
+	    $state = STATE_NORMAL;
 	}
 
 	if ($verbose) {
-	    print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
+	    print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
 	}
     } else {
 	print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
 	    " - I thought it was a doc line\n";
 	++$warnings;
 	$state = STATE_NORMAL;
     }
 }
 
 
 #
 # STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
 #
 sub process_body($$) {
     my $file = shift;
 
     # Until all named variable macro parameters are
     # documented using the bare name (`x`) rather than with
     # dots (`x...`), strip the dots:
     if ($section =~ /\w\.\.\.$/) {
-- 
2.28.0


^ permalink raw reply related	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 02/27] net: datagram: fix some kernel-doc markups
  2020-11-16 10:17 ` [PATCH v4 02/27] net: datagram: fix some " Mauro Carvalho Chehab
@ 2020-11-16 10:20   ` Kirill Tkhai
  0 siblings, 0 replies; 51+ messages in thread
From: Kirill Tkhai @ 2020-11-16 10:20 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Anna Schumaker, Trond Myklebust
  Cc: David S. Miller, J. Bruce Fields, Jonathan Corbet,
	Linux Doc Mailing List, Al Viro, Alexei Starovoitov,
	Andrii Nakryiko, Bartosz Golaszewski, Chuck Lever, Cong Wang,
	Eric Dumazet, Florian Westphal, Guillaume Nault, Heiner Kallweit,
	Jakub Kicinski, Jiri Pirko, Martin Varghese, Maxim Mikityanskiy,
	Miaohe Lin, Paolo Abeni, Pravin B Shelar, Sabrina Dubroca,
	Steffen Klassert, Taehee Yoo, Vladimir Oltean, Willem de Bruijn,
	Yadu Kishore, linux-kernel, linux-nfs, netdev

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


^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 04/27] s390: fix kernel-doc markups
  2020-11-16 10:18 ` [PATCH v4 04/27] s390: fix " Mauro Carvalho Chehab
@ 2020-11-16 10:25   ` Cornelia Huck
  2020-11-16 10:38   ` Vineeth Vijayan
  1 sibling, 0 replies; 51+ messages in thread
From: Cornelia Huck @ 2020-11-16 10:25 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Jonathan Corbet, Alexander Egorenkov,
	Alexandra Winter, Christian Borntraeger, Heiko Carstens,
	Julian Wiedmann, Peter Oberparleiter, Sven Schnelle,
	Vasily Gorbik, Vineeth Vijayan, linux-kernel, linux-s390

On Mon, 16 Nov 2020 11:18:00 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> fix one typo:
> 	ccw driver -> ccw_driver
> 
> and one function rename.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  arch/s390/include/asm/ccwdev.h | 2 +-
>  arch/s390/include/asm/cio.h    | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)

Reviewed-by: Cornelia Huck <cohuck@redhat.com>


^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 07/27] IB: fix kernel-doc markups
  2020-11-16 10:18 ` [PATCH v4 07/27] IB: fix kernel-doc markups Mauro Carvalho Chehab
@ 2020-11-16 10:36   ` Gustavo A. R. Silva
  2020-11-23 23:45   ` Jason Gunthorpe
  1 sibling, 0 replies; 51+ messages in thread
From: Gustavo A. R. Silva @ 2020-11-16 10:36 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Håkon Bugge, Jonathan Corbet,
	Bart Van Assche, Chuck Lever, Danit Goldberg, Dennis Dalessandro,
	Divya Indi, Doug Ledford, Gal Pressman, Jason Gunthorpe,
	Leon Romanovsky, Maor Gottlieb, Max Gurtovoy, Mike Marciniszyn,
	Moni Shoua, Or Gerlitz, Parav Pandit, Sagi Grimberg,
	Ursula Braun, Xi Wang, Yamin Friedman, linux-kernel, linux-rdma,
	target-devel

On Mon, Nov 16, 2020 at 11:18:03AM +0100, Mauro Carvalho Chehab wrote:

[..]

> diff --git a/drivers/infiniband/sw/rdmavt/ah.c b/drivers/infiniband/sw/rdmavt/ah.c
> index f9754dcd250b..480b621d1a9f 100644
> --- a/drivers/infiniband/sw/rdmavt/ah.c
> +++ b/drivers/infiniband/sw/rdmavt/ah.c
[..]
>  /**
> - * rvt_destory_ah - Destory an address handle
> + * rvt_destroy_ah - Destory an address handle

s/Destory/Destroy

>   * @ibah: address handle
>   * @destroy_flags: destroy address handle flags (see enum rdma_destroy_ah_flags)
>   * Return: 0 on success
>   */
>  int rvt_destroy_ah(struct ib_ah *ibah, u32 destroy_flags)
>  {
>  	struct rvt_dev_info *dev = ib_to_rvt(ibah->device);
>  	struct rvt_ah *ah = ibah_to_rvtah(ibah);
>  	unsigned long flags;
>  
>  	spin_lock_irqsave(&dev->n_ahs_lock, flags);
>  	dev->n_ahs_allocated--;
>  	spin_unlock_irqrestore(&dev->n_ahs_lock, flags);
>  
>  	rdma_destroy_ah_attr(&ah->attr);
>  	return 0;
>  }

--
Gustavo

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 04/27] s390: fix kernel-doc markups
  2020-11-16 10:18 ` [PATCH v4 04/27] s390: fix " Mauro Carvalho Chehab
  2020-11-16 10:25   ` Cornelia Huck
@ 2020-11-16 10:38   ` Vineeth Vijayan
  2020-11-16 12:04     ` Vineeth Vijayan
  1 sibling, 1 reply; 51+ messages in thread
From: Vineeth Vijayan @ 2020-11-16 10:38 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Linux Doc Mailing List
  Cc: Jonathan Corbet, Alexander Egorenkov, Alexandra Winter,
	Christian Borntraeger, Heiko Carstens, Julian Wiedmann,
	Peter Oberparleiter, Sven Schnelle, Vasily Gorbik,
	Vineeth Vijayan, linux-kernel, linux-s390

Thank you very much for the fix.

Reviewed-by: Vineeth Vijayan <vneethv@linux.ibm.com>



On 11/16/20 11:18 AM, Mauro Carvalho Chehab wrote:
> fix one typo:
> 	ccw driver -> ccw_driver
>
> and one function rename.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>   arch/s390/include/asm/ccwdev.h | 2 +-
>   arch/s390/include/asm/cio.h    | 2 +-
>   2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/arch/s390/include/asm/ccwdev.h b/arch/s390/include/asm/ccwdev.h
> index bf605e1fcf6a..0495ac635ed5 100644
> --- a/arch/s390/include/asm/ccwdev.h
> +++ b/arch/s390/include/asm/ccwdev.h
> @@ -100,41 +100,41 @@ struct ccw_device {
>    */
>   #define PE_NONE				0x0
>   #define PE_PATH_GONE			0x1 /* A path is no longer available. */
>   #define PE_PATH_AVAILABLE		0x2 /* A path has become available and
>   					       was successfully verified. */
>   #define PE_PATHGROUP_ESTABLISHED	0x4 /* A pathgroup was reset and had
>   					       to be established again. */
>   #define PE_PATH_FCES_EVENT		0x8 /* The FCES Status of a path has
>   					     * changed. */
>   
>   /*
>    * Possible CIO actions triggered by the unit check handler.
>    */
>   enum uc_todo {
>   	UC_TODO_RETRY,
>   	UC_TODO_RETRY_ON_NEW_PATH,
>   	UC_TODO_STOP
>   };
>   
>   /**
> - * struct ccw driver - device driver for channel attached devices
> + * struct ccw_driver - device driver for channel attached devices
>    * @ids: ids supported by this driver
>    * @probe: function called on probe
>    * @remove: function called on remove
>    * @set_online: called when setting device online
>    * @set_offline: called when setting device offline
>    * @notify: notify driver of device state changes
>    * @path_event: notify driver of channel path events
>    * @shutdown: called at device shutdown
>    * @prepare: prepare for pm state transition
>    * @complete: undo work done in @prepare
>    * @freeze: callback for freezing during hibernation snapshotting
>    * @thaw: undo work done in @freeze
>    * @restore: callback for restoring after hibernation
>    * @uc_handler: callback for unit check handler
>    * @driver: embedded device driver structure
>    * @int_class: interruption class to use for accounting interrupts
>    */
>   struct ccw_driver {
>   	struct ccw_device_id *ids;
>   	int (*probe) (struct ccw_device *);
> diff --git a/arch/s390/include/asm/cio.h b/arch/s390/include/asm/cio.h
> index e36cb67d2441..ac02df906cae 100644
> --- a/arch/s390/include/asm/cio.h
> +++ b/arch/s390/include/asm/cio.h
> @@ -312,41 +312,41 @@ struct node_descriptor {
>   /* Device did not respond in time. */
>   #define CIO_BOXED      0x0010
>   
>   /**
>    * struct ccw_dev_id - unique identifier for ccw devices
>    * @ssid: subchannel set id
>    * @devno: device number
>    *
>    * This structure is not directly based on any hardware structure. The
>    * hardware identifies a device by its device number and its subchannel,
>    * which is in turn identified by its id. In order to get a unique identifier
>    * for ccw devices across subchannel sets, @struct ccw_dev_id has been
>    * introduced.
>    */
>   struct ccw_dev_id {
>   	u8 ssid;
>   	u16 devno;
>   };
>   
>   /**
> - * ccw_device_id_is_equal() - compare two ccw_dev_ids
> + * ccw_dev_id_is_equal() - compare two ccw_dev_ids
>    * @dev_id1: a ccw_dev_id
>    * @dev_id2: another ccw_dev_id
>    * Returns:
>    *  %1 if the two structures are equal field-by-field,
>    *  %0 if not.
>    * Context:
>    *  any
>    */
>   static inline int ccw_dev_id_is_equal(struct ccw_dev_id *dev_id1,
>   				      struct ccw_dev_id *dev_id2)
>   {
>   	if ((dev_id1->ssid == dev_id2->ssid) &&
>   	    (dev_id1->devno == dev_id2->devno))
>   		return 1;
>   	return 0;
>   }
>   
>   /**
>    * pathmask_to_pos() - find the position of the left-most bit in a pathmask
>    * @mask: pathmask with at least one bit set

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 14/27] completion: fix kernel-doc markups
  2020-11-16 10:18 ` [PATCH v4 14/27] completion: fix kernel-doc markups Mauro Carvalho Chehab
@ 2020-11-16 11:36   ` Peter Zijlstra
  0 siblings, 0 replies; 51+ messages in thread
From: Peter Zijlstra @ 2020-11-16 11:36 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Joel Fernandes (Google),
	Jonathan Corbet, Davidlohr Bueso, Greg Kroah-Hartman,
	Thomas Gleixner, linux-kernel

On Mon, Nov 16, 2020 at 11:18:10AM +0100, Mauro Carvalho Chehab wrote:
> Kernel-doc only supports having the comment just before
> the identifier.
> 
> The markup for init_completion is actually for
> __init_completion.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> 
> ---
> 
> Thats said, IMHO, it would make sense to simply
> rename __init_completion() to init_completion() and drop
> this define:
> 
> 	 #define init_completion(x) __init_completion(x)

Yeah, that seems to be the result of much code shuffling. That cleanups
seems sanest.

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 05/27] drm: fix some kernel-doc markups
  2020-11-16 10:18 ` [PATCH v4 05/27] drm: fix some " Mauro Carvalho Chehab
@ 2020-11-16 11:37   ` Jani Nikula
  2020-11-16 19:48     ` Daniel Vetter
  0 siblings, 1 reply; 51+ messages in thread
From: Jani Nikula @ 2020-11-16 11:37 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Daniel Vetter, David Airlie,
	Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann
  Cc: Mauro Carvalho Chehab, Christian König, Jonathan Corbet,
	José Roberto de Souza, Linux Doc Mailing List,
	Ville Syrjälä,
	Alex Deucher, Andrey Grodzovsky, Eric Anholt, Imre Deak,
	Joonas Lahtinen, Luben Tuikov, Lucas Stach, Matt Roper,
	Nirmoy Das, Pankaj Bharadiya, Rodrigo Vivi, Tejas Upadhyay,
	Wambui Karuga, Yintian Tao, changzhu, dri-devel, intel-gfx,
	linux-kernel

On Mon, 16 Nov 2020, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> Some identifiers have different names between their prototypes
> and the kernel-doc markup.
>
> Others need to be fixed, as kernel-doc markups should use this format:
>         identifier - description
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  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 +++++---

For the i915 parts,

Acked-by: Jani Nikula <jani.nikula@intel.com>

for merging via whichever tree.

>  drivers/gpu/drm/scheduler/sched_main.c        | 2 +-
>  drivers/gpu/drm/v3d/v3d_sched.c               | 2 +-
>  drivers/gpu/drm/vc4/vc4_bo.c                  | 2 +-
>  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 ++++----
>  20 files changed, 32 insertions(+), 28 deletions(-)
>
> diff --git a/drivers/gpu/drm/drm_atomic_state_helper.c b/drivers/gpu/drm/drm_atomic_state_helper.c
> index 9ad74045158e..ddcf5c2c8e6a 100644
> --- a/drivers/gpu/drm/drm_atomic_state_helper.c
> +++ b/drivers/gpu/drm/drm_atomic_state_helper.c
> @@ -526,41 +526,41 @@ __drm_atomic_helper_connector_destroy_state(struct drm_connector_state *state)
>  }
>  EXPORT_SYMBOL(__drm_atomic_helper_connector_destroy_state);
>  
>  /**
>   * drm_atomic_helper_connector_destroy_state - default state destroy hook
>   * @connector: drm connector
>   * @state: connector state object to release
>   *
>   * Default connector state destroy hook for drivers which don't have their own
>   * subclassed connector state structure.
>   */
>  void drm_atomic_helper_connector_destroy_state(struct drm_connector *connector,
>  					  struct drm_connector_state *state)
>  {
>  	__drm_atomic_helper_connector_destroy_state(state);
>  	kfree(state);
>  }
>  EXPORT_SYMBOL(drm_atomic_helper_connector_destroy_state);
>  
>  /**
> - * __drm_atomic_helper_private_duplicate_state - copy atomic private state
> + * __drm_atomic_helper_private_obj_duplicate_state - copy atomic private state
>   * @obj: CRTC object
>   * @state: new private object state
>   *
>   * Copies atomic state from a private objects's current state and resets inferred values.
>   * This is useful for drivers that subclass the private state.
>   */
>  void __drm_atomic_helper_private_obj_duplicate_state(struct drm_private_obj *obj,
>  						     struct drm_private_state *state)
>  {
>  	memcpy(state, obj->state, sizeof(*state));
>  }
>  EXPORT_SYMBOL(__drm_atomic_helper_private_obj_duplicate_state);
>  
>  /**
>   * __drm_atomic_helper_bridge_duplicate_state() - Copy atomic bridge state
>   * @bridge: bridge object
>   * @state: atomic bridge state
>   *
>   * Copies atomic state from a bridge's current state and resets inferred values.
>   * This is useful for drivers that subclass the bridge state.
> diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
> index 1913d8b4e16a..98b6ec45ef96 100644
> --- a/drivers/gpu/drm/drm_connector.c
> +++ b/drivers/gpu/drm/drm_connector.c
> @@ -1415,41 +1415,42 @@ void drm_hdmi_avi_infoframe_content_type(struct hdmi_avi_infoframe *frame,
>  		break;
>  	case DRM_MODE_CONTENT_TYPE_CINEMA:
>  		frame->content_type = HDMI_CONTENT_TYPE_CINEMA;
>  		break;
>  	case DRM_MODE_CONTENT_TYPE_GAME:
>  		frame->content_type = HDMI_CONTENT_TYPE_GAME;
>  		break;
>  	case DRM_MODE_CONTENT_TYPE_PHOTO:
>  		frame->content_type = HDMI_CONTENT_TYPE_PHOTO;
>  		break;
>  	default:
>  		/* Graphics is the default(0) */
>  		frame->content_type = HDMI_CONTENT_TYPE_GRAPHICS;
>  	}
>  
>  	frame->itc = conn_state->content_type != DRM_MODE_CONTENT_TYPE_NO_DATA;
>  }
>  EXPORT_SYMBOL(drm_hdmi_avi_infoframe_content_type);
>  
>  /**
> - * drm_mode_attach_tv_margin_properties - attach TV connector margin properties
> + * drm_connector_attach_tv_margin_properties - attach TV connector margin
> + * 	properties
>   * @connector: DRM connector
>   *
>   * Called by a driver when it needs to attach TV margin props to a connector.
>   * Typically used on SDTV and HDMI connectors.
>   */
>  void drm_connector_attach_tv_margin_properties(struct drm_connector *connector)
>  {
>  	struct drm_device *dev = connector->dev;
>  
>  	drm_object_attach_property(&connector->base,
>  				   dev->mode_config.tv_left_margin_property,
>  				   0);
>  	drm_object_attach_property(&connector->base,
>  				   dev->mode_config.tv_right_margin_property,
>  				   0);
>  	drm_object_attach_property(&connector->base,
>  				   dev->mode_config.tv_top_margin_property,
>  				   0);
>  	drm_object_attach_property(&connector->base,
>  				   dev->mode_config.tv_bottom_margin_property,
> diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
> index 37ec3b94389c..5bd0934004e3 100644
> --- a/drivers/gpu/drm/drm_dp_helper.c
> +++ b/drivers/gpu/drm/drm_dp_helper.c
> @@ -1144,41 +1144,41 @@ drm_dp_subconnector_type(const u8 dpcd[DP_RECEIVER_CAP_SIZE],
>  	switch (type) {
>  	case DP_DS_PORT_TYPE_DP:
>  	case DP_DS_PORT_TYPE_DP_DUALMODE:
>  		return DRM_MODE_SUBCONNECTOR_DisplayPort;
>  	case DP_DS_PORT_TYPE_VGA:
>  		return DRM_MODE_SUBCONNECTOR_VGA;
>  	case DP_DS_PORT_TYPE_DVI:
>  		return DRM_MODE_SUBCONNECTOR_DVID;
>  	case DP_DS_PORT_TYPE_HDMI:
>  		return DRM_MODE_SUBCONNECTOR_HDMIA;
>  	case DP_DS_PORT_TYPE_WIRELESS:
>  		return DRM_MODE_SUBCONNECTOR_Wireless;
>  	case DP_DS_PORT_TYPE_NON_EDID:
>  	default:
>  		return DRM_MODE_SUBCONNECTOR_Unknown;
>  	}
>  }
>  EXPORT_SYMBOL(drm_dp_subconnector_type);
>  
>  /**
> - * drm_mode_set_dp_subconnector_property - set subconnector for DP connector
> + * drm_dp_set_subconnector_property - set subconnector for DP connector
>   * @connector: connector to set property on
>   * @status: connector status
>   * @dpcd: DisplayPort configuration data
>   * @port_cap: port capabilities
>   *
>   * Called by a driver on every detect event.
>   */
>  void drm_dp_set_subconnector_property(struct drm_connector *connector,
>  				      enum drm_connector_status status,
>  				      const u8 *dpcd,
>  				      const u8 port_cap[4])
>  {
>  	enum drm_mode_subconnector subconnector = DRM_MODE_SUBCONNECTOR_Unknown;
>  
>  	if (status == connector_status_connected)
>  		subconnector = drm_dp_subconnector_type(dpcd, port_cap);
>  	drm_object_property_set_value(&connector->base,
>  			connector->dev->mode_config.dp_subconnector_property,
>  			subconnector);
>  }
> diff --git a/drivers/gpu/drm/drm_framebuffer.c b/drivers/gpu/drm/drm_framebuffer.c
> index 2f5b0c2bb0fe..aca62ed51e82 100644
> --- a/drivers/gpu/drm/drm_framebuffer.c
> +++ b/drivers/gpu/drm/drm_framebuffer.c
> @@ -535,41 +535,41 @@ int drm_mode_getfb(struct drm_device *dev,
>  
>  	/* GET_FB() is an unprivileged ioctl so we must not return a
>  	 * buffer-handle to non-master processes! For
>  	 * backwards-compatibility reasons, we cannot make GET_FB() privileged,
>  	 * so just return an invalid handle for non-masters.
>  	 */
>  	if (!drm_is_current_master(file_priv) && !capable(CAP_SYS_ADMIN)) {
>  		r->handle = 0;
>  		ret = 0;
>  		goto out;
>  	}
>  
>  	ret = fb->funcs->create_handle(fb, file_priv, &r->handle);
>  
>  out:
>  	drm_framebuffer_put(fb);
>  	return ret;
>  }
>  
>  /**
> - * drm_mode_getfb2 - get extended FB info
> + * drm_mode_getfb2_ioctl - get extended FB info
>   * @dev: drm device for the ioctl
>   * @data: data pointer for the ioctl
>   * @file_priv: drm file for the ioctl call
>   *
>   * Lookup the FB given its ID and return info about it.
>   *
>   * Called by the user via ioctl.
>   *
>   * Returns:
>   * Zero on success, negative errno on failure.
>   */
>  int drm_mode_getfb2_ioctl(struct drm_device *dev,
>  			  void *data, struct drm_file *file_priv)
>  {
>  	struct drm_mode_fb_cmd2 *r = data;
>  	struct drm_framebuffer *fb;
>  	unsigned int i;
>  	int ret;
>  
>  	if (!drm_core_check_feature(dev, DRIVER_MODESET))
> diff --git a/drivers/gpu/drm/drm_gem.c b/drivers/gpu/drm/drm_gem.c
> index eb2d23e04be9..92f89cee213e 100644
> --- a/drivers/gpu/drm/drm_gem.c
> +++ b/drivers/gpu/drm/drm_gem.c
> @@ -850,41 +850,41 @@ drm_gem_flink_ioctl(struct drm_device *dev, void *data,
>  	}
>  
>  	if (!obj->name) {
>  		ret = idr_alloc(&dev->object_name_idr, obj, 1, 0, GFP_KERNEL);
>  		if (ret < 0)
>  			goto err;
>  
>  		obj->name = ret;
>  	}
>  
>  	args->name = (uint64_t) obj->name;
>  	ret = 0;
>  
>  err:
>  	mutex_unlock(&dev->object_name_lock);
>  	drm_gem_object_put(obj);
>  	return ret;
>  }
>  
>  /**
> - * drm_gem_open - implementation of the GEM_OPEN ioctl
> + * drm_gem_open_ioctl - implementation of the GEM_OPEN ioctl
>   * @dev: drm_device
>   * @data: ioctl data
>   * @file_priv: drm file-private structure
>   *
>   * Open an object using the global name, returning a handle and the size.
>   *
>   * This handle (of course) holds a reference to the object, so the object
>   * will not go away until the handle is deleted.
>   */
>  int
>  drm_gem_open_ioctl(struct drm_device *dev, void *data,
>  		   struct drm_file *file_priv)
>  {
>  	struct drm_gem_open *args = data;
>  	struct drm_gem_object *obj;
>  	int ret;
>  	u32 handle;
>  
>  	if (!drm_core_check_feature(dev, DRIVER_GEM))
>  		return -EOPNOTSUPP;
> @@ -895,41 +895,41 @@ drm_gem_open_ioctl(struct drm_device *dev, void *data,
>  		drm_gem_object_get(obj);
>  	} else {
>  		mutex_unlock(&dev->object_name_lock);
>  		return -ENOENT;
>  	}
>  
>  	/* drm_gem_handle_create_tail unlocks dev->object_name_lock. */
>  	ret = drm_gem_handle_create_tail(file_priv, obj, &handle);
>  	if (ret)
>  		goto err;
>  
>  	args->handle = handle;
>  	args->size = obj->size;
>  
>  err:
>  	drm_gem_object_put(obj);
>  	return ret;
>  }
>  
>  /**
> - * gem_gem_open - initalizes GEM file-private structures at devnode open time
> + * drm_gem_open - initalizes GEM file-private structures at devnode open time
>   * @dev: drm_device which is being opened by userspace
>   * @file_private: drm file-private structure to set up
>   *
>   * Called at device open time, sets up the structure for handling refcounting
>   * of mm objects.
>   */
>  void
>  drm_gem_open(struct drm_device *dev, struct drm_file *file_private)
>  {
>  	idr_init_base(&file_private->object_idr, 1);
>  	spin_lock_init(&file_private->table_lock);
>  }
>  
>  /**
>   * drm_gem_release - release file-private GEM resources
>   * @dev: drm_device which is being closed by userspace
>   * @file_private: drm file-private structure to clean up
>   *
>   * Called at close time when the filp is going away.
>   *
> diff --git a/drivers/gpu/drm/drm_gem_vram_helper.c b/drivers/gpu/drm/drm_gem_vram_helper.c
> index 889a06696f7e..02ca22e90290 100644
> --- a/drivers/gpu/drm/drm_gem_vram_helper.c
> +++ b/drivers/gpu/drm/drm_gem_vram_helper.c
> @@ -600,41 +600,41 @@ static int drm_gem_vram_bo_driver_move(struct drm_gem_vram_object *gbo,
>   * Helpers for struct drm_gem_object_funcs
>   */
>  
>  /**
>   * drm_gem_vram_object_free() - \
>  	Implements &struct drm_gem_object_funcs.free
>   * @gem:       GEM object. Refers to &struct drm_gem_vram_object.gem
>   */
>  static void drm_gem_vram_object_free(struct drm_gem_object *gem)
>  {
>  	struct drm_gem_vram_object *gbo = drm_gem_vram_of_gem(gem);
>  
>  	drm_gem_vram_put(gbo);
>  }
>  
>  /*
>   * Helpers for dump buffers
>   */
>  
>  /**
> - * drm_gem_vram_driver_create_dumb() - \
> + * drm_gem_vram_driver_dumb_create() - \
>  	Implements &struct drm_driver.dumb_create
>   * @file:		the DRM file
>   * @dev:		the DRM device
>   * @args:		the arguments as provided to \
>  				&struct drm_driver.dumb_create
>   *
>   * This function requires the driver to use @drm_device.vram_mm for its
>   * instance of VRAM MM.
>   *
>   * Returns:
>   * 0 on success, or
>   * a negative error code otherwise.
>   */
>  int drm_gem_vram_driver_dumb_create(struct drm_file *file,
>  				    struct drm_device *dev,
>  				    struct drm_mode_create_dumb *args)
>  {
>  	if (WARN_ONCE(!dev->vram_mm, "VRAM MM not initialized"))
>  		return -EINVAL;
>  
> diff --git a/drivers/gpu/drm/drm_mode_object.c b/drivers/gpu/drm/drm_mode_object.c
> index db05f386a709..b26588b52795 100644
> --- a/drivers/gpu/drm/drm_mode_object.c
> +++ b/drivers/gpu/drm/drm_mode_object.c
> @@ -98,41 +98,41 @@ void drm_mode_object_register(struct drm_device *dev,
>   * Free @id from @dev's unique identifier pool.
>   * This function can be called multiple times, and guards against
>   * multiple removals.
>   * These modeset identifiers are _not_ reference counted. Hence don't use this
>   * for reference counted modeset objects like framebuffers.
>   */
>  void drm_mode_object_unregister(struct drm_device *dev,
>  				struct drm_mode_object *object)
>  {
>  	WARN_ON(!dev->driver->load && dev->registered && !object->free_cb);
>  
>  	mutex_lock(&dev->mode_config.idr_mutex);
>  	if (object->id) {
>  		idr_remove(&dev->mode_config.object_idr, object->id);
>  		object->id = 0;
>  	}
>  	mutex_unlock(&dev->mode_config.idr_mutex);
>  }
>  
>  /**
> - * drm_lease_required - check types which must be leased to be used
> + * drm_mode_object_lease_required - check types which must be leased to be used
>   * @type: type of object
>   *
>   * Returns whether the provided type of drm_mode_object must
>   * be owned or leased to be used by a process.
>   */
>  bool drm_mode_object_lease_required(uint32_t type)
>  {
>  	switch(type) {
>  	case DRM_MODE_OBJECT_CRTC:
>  	case DRM_MODE_OBJECT_CONNECTOR:
>  	case DRM_MODE_OBJECT_PLANE:
>  		return true;
>  	default:
>  		return false;
>  	}
>  }
>  
>  struct drm_mode_object *__drm_mode_object_find(struct drm_device *dev,
>  					       struct drm_file *file_priv,
>  					       uint32_t id, uint32_t type)
> diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c
> index 501b4fe55a3d..33fb2f05ce66 100644
> --- a/drivers/gpu/drm/drm_modes.c
> +++ b/drivers/gpu/drm/drm_modes.c
> @@ -1872,41 +1872,41 @@ drm_mode_create_from_cmdline_mode(struct drm_device *dev,
>  				    cmd->margins);
>  	else
>  		mode = drm_gtf_mode(dev,
>  				    cmd->xres, cmd->yres,
>  				    cmd->refresh_specified ? cmd->refresh : 60,
>  				    cmd->interlace,
>  				    cmd->margins);
>  	if (!mode)
>  		return NULL;
>  
>  	mode->type |= DRM_MODE_TYPE_USERDEF;
>  	/* fix up 1368x768: GFT/CVT can't express 1366 width due to alignment */
>  	if (cmd->xres == 1366)
>  		drm_mode_fixup_1366x768(mode);
>  	drm_mode_set_crtcinfo(mode, CRTC_INTERLACE_HALVE_V);
>  	return mode;
>  }
>  EXPORT_SYMBOL(drm_mode_create_from_cmdline_mode);
>  
>  /**
> - * drm_crtc_convert_to_umode - convert a drm_display_mode into a modeinfo
> + * drm_mode_convert_to_umode - convert a drm_display_mode into a modeinfo
>   * @out: drm_mode_modeinfo struct to return to the user
>   * @in: drm_display_mode to use
>   *
>   * Convert a drm_display_mode into a drm_mode_modeinfo structure to return to
>   * the user.
>   */
>  void drm_mode_convert_to_umode(struct drm_mode_modeinfo *out,
>  			       const struct drm_display_mode *in)
>  {
>  	out->clock = in->clock;
>  	out->hdisplay = in->hdisplay;
>  	out->hsync_start = in->hsync_start;
>  	out->hsync_end = in->hsync_end;
>  	out->htotal = in->htotal;
>  	out->hskew = in->hskew;
>  	out->vdisplay = in->vdisplay;
>  	out->vsync_start = in->vsync_start;
>  	out->vsync_end = in->vsync_end;
>  	out->vtotal = in->vtotal;
>  	out->vscan = in->vscan;
> @@ -1924,41 +1924,41 @@ void drm_mode_convert_to_umode(struct drm_mode_modeinfo *out,
>  	case HDMI_PICTURE_ASPECT_64_27:
>  		out->flags |= DRM_MODE_FLAG_PIC_AR_64_27;
>  		break;
>  	case HDMI_PICTURE_ASPECT_256_135:
>  		out->flags |= DRM_MODE_FLAG_PIC_AR_256_135;
>  		break;
>  	default:
>  		WARN(1, "Invalid aspect ratio (0%x) on mode\n",
>  		     in->picture_aspect_ratio);
>  		fallthrough;
>  	case HDMI_PICTURE_ASPECT_NONE:
>  		out->flags |= DRM_MODE_FLAG_PIC_AR_NONE;
>  		break;
>  	}
>  
>  	strncpy(out->name, in->name, DRM_DISPLAY_MODE_LEN);
>  	out->name[DRM_DISPLAY_MODE_LEN-1] = 0;
>  }
>  
>  /**
> - * drm_crtc_convert_umode - convert a modeinfo into a drm_display_mode
> + * drm_mode_convert_umode - convert a modeinfo into a drm_display_mode
>   * @dev: drm device
>   * @out: drm_display_mode to return to the user
>   * @in: drm_mode_modeinfo to use
>   *
>   * Convert a drm_mode_modeinfo into a drm_display_mode structure to return to
>   * the caller.
>   *
>   * Returns:
>   * Zero on success, negative errno on failure.
>   */
>  int drm_mode_convert_umode(struct drm_device *dev,
>  			   struct drm_display_mode *out,
>  			   const struct drm_mode_modeinfo *in)
>  {
>  	if (in->clock > INT_MAX || in->vrefresh > INT_MAX)
>  		return -ERANGE;
>  
>  	out->clock = in->clock;
>  	out->hdisplay = in->hdisplay;
>  	out->hsync_start = in->hsync_start;
> diff --git a/drivers/gpu/drm/drm_scdc_helper.c b/drivers/gpu/drm/drm_scdc_helper.c
> index 311e71bbba5b..991b8c86d78d 100644
> --- a/drivers/gpu/drm/drm_scdc_helper.c
> +++ b/drivers/gpu/drm/drm_scdc_helper.c
> @@ -108,41 +108,41 @@ ssize_t drm_scdc_write(struct i2c_adapter *adapter, u8 offset,
>  
>  	msg.buf = data;
>  
>  	memcpy(data, &offset, sizeof(offset));
>  	memcpy(data + 1, buffer, size);
>  
>  	err = i2c_transfer(adapter, &msg, 1);
>  
>  	kfree(data);
>  
>  	if (err < 0)
>  		return err;
>  	if (err != 1)
>  		return -EPROTO;
>  
>  	return 0;
>  }
>  EXPORT_SYMBOL(drm_scdc_write);
>  
>  /**
> - * drm_scdc_check_scrambling_status - what is status of scrambling?
> + * drm_scdc_get_scrambling_status - what is status of scrambling?
>   * @adapter: I2C adapter for DDC channel
>   *
>   * Reads the scrambler status over SCDC, and checks the
>   * scrambling status.
>   *
>   * Returns:
>   * True if the scrambling is enabled, false otherwise.
>   */
>  bool drm_scdc_get_scrambling_status(struct i2c_adapter *adapter)
>  {
>  	u8 status;
>  	int ret;
>  
>  	ret = drm_scdc_readb(adapter, SCDC_SCRAMBLER_STATUS, &status);
>  	if (ret < 0) {
>  		DRM_DEBUG_KMS("Failed to read scrambling status: %d\n", ret);
>  		return false;
>  	}
>  
>  	return status & SCDC_SCRAMBLING_STATUS;
> diff --git a/drivers/gpu/drm/i915/display/intel_dpll_mgr.c b/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
> index a95e6a2ac698..8753bab20ce8 100644
> --- a/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
> +++ b/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
> @@ -4573,41 +4573,41 @@ static void sanitize_dpll_state(struct drm_i915_private *i915,
>  	if (!pll->on || pll->active_mask)
>  		return;
>  
>  	drm_dbg_kms(&i915->drm,
>  		    "%s enabled but not in use, disabling\n",
>  		    pll->info->name);
>  
>  	pll->info->funcs->disable(i915, pll);
>  	pll->on = false;
>  }
>  
>  void intel_dpll_sanitize_state(struct drm_i915_private *i915)
>  {
>  	int i;
>  
>  	for (i = 0; i < i915->dpll.num_shared_dpll; i++)
>  		sanitize_dpll_state(i915, &i915->dpll.shared_dplls[i]);
>  }
>  
>  /**
> - * intel_shared_dpll_dump_hw_state - write hw_state to dmesg
> + * intel_dpll_dump_hw_state - write hw_state to dmesg
>   * @dev_priv: i915 drm device
>   * @hw_state: hw state to be written to the log
>   *
>   * Write the relevant values in @hw_state to dmesg using drm_dbg_kms.
>   */
>  void intel_dpll_dump_hw_state(struct drm_i915_private *dev_priv,
>  			      const struct intel_dpll_hw_state *hw_state)
>  {
>  	if (dev_priv->dpll.mgr) {
>  		dev_priv->dpll.mgr->dump_hw_state(dev_priv, hw_state);
>  	} else {
>  		/* fallback for platforms that don't use the shared dpll
>  		 * infrastructure
>  		 */
>  		drm_dbg_kms(&dev_priv->drm,
>  			    "dpll_hw_state: dpll: 0x%x, dpll_md: 0x%x, "
>  			    "fp0: 0x%x, fp1: 0x%x\n",
>  			    hw_state->dpll,
>  			    hw_state->dpll_md,
>  			    hw_state->fp0,
> diff --git a/drivers/gpu/drm/i915/i915_gem_evict.c b/drivers/gpu/drm/i915/i915_gem_evict.c
> index 6501939929d5..e1a66c8245b8 100644
> --- a/drivers/gpu/drm/i915/i915_gem_evict.c
> +++ b/drivers/gpu/drm/i915/i915_gem_evict.c
> @@ -221,41 +221,41 @@ i915_gem_evict_something(struct i915_address_space *vm,
>  	list_for_each_entry_safe(vma, next, &eviction_list, evict_link) {
>  		__i915_vma_unpin(vma);
>  		if (ret == 0)
>  			ret = __i915_vma_unbind(vma);
>  	}
>  
>  	while (ret == 0 && (node = drm_mm_scan_color_evict(&scan))) {
>  		vma = container_of(node, struct i915_vma, node);
>  
>  		/* If we find any non-objects (!vma), we cannot evict them */
>  		if (vma->node.color != I915_COLOR_UNEVICTABLE)
>  			ret = __i915_vma_unbind(vma);
>  		else
>  			ret = -ENOSPC; /* XXX search failed, try again? */
>  	}
>  
>  	return ret;
>  }
>  
>  /**
> - * i915_gem_evict_for_vma - Evict vmas to make room for binding a new one
> + * i915_gem_evict_for_node - Evict vmas to make room for binding a new one
>   * @vm: address space to evict from
>   * @target: range (and color) to evict for
>   * @flags: additional flags to control the eviction algorithm
>   *
>   * This function will try to evict vmas that overlap the target node.
>   *
>   * To clarify: This is for freeing up virtual address space, not for freeing
>   * memory in e.g. the shrinker.
>   */
>  int i915_gem_evict_for_node(struct i915_address_space *vm,
>  			    struct drm_mm_node *target,
>  			    unsigned int flags)
>  {
>  	LIST_HEAD(eviction_list);
>  	struct drm_mm_node *node;
>  	u64 start = target->start;
>  	u64 end = start + target->size;
>  	struct i915_vma *vma, *next;
>  	int ret = 0;
>  
> diff --git a/drivers/gpu/drm/i915/i915_perf.c b/drivers/gpu/drm/i915/i915_perf.c
> index e94976976571..3ced82820483 100644
> --- a/drivers/gpu/drm/i915/i915_perf.c
> +++ b/drivers/gpu/drm/i915/i915_perf.c
> @@ -608,41 +608,42 @@ static int append_oa_sample(struct i915_perf_stream *stream,
>  
>  	if ((count - *offset) < header.size)
>  		return -ENOSPC;
>  
>  	buf += *offset;
>  	if (copy_to_user(buf, &header, sizeof(header)))
>  		return -EFAULT;
>  	buf += sizeof(header);
>  
>  	if (sample_flags & SAMPLE_OA_REPORT) {
>  		if (copy_to_user(buf, report, report_size))
>  			return -EFAULT;
>  	}
>  
>  	(*offset) += header.size;
>  
>  	return 0;
>  }
>  
>  /**
> - * Copies all buffered OA reports into userspace read() buffer.
> + * gen8_append_oa_reports - Copies all buffered OA reports into
> + *			    userspace read() buffer.
>   * @stream: An i915-perf stream opened for OA metrics
>   * @buf: destination buffer given by userspace
>   * @count: the number of bytes userspace wants to read
>   * @offset: (inout): the current position for writing into @buf
>   *
>   * Notably any error condition resulting in a short read (-%ENOSPC or
>   * -%EFAULT) will be returned even though one or more records may
>   * have been successfully copied. In this case it's up to the caller
>   * to decide if the error should be squashed before returning to
>   * userspace.
>   *
>   * Note: reports are consumed from the head, and appended to the
>   * tail, so the tail chases the head?... If you think that's mad
>   * and back-to-front you're not alone, but this follows the
>   * Gen PRM naming convention.
>   *
>   * Returns: 0 on success, negative error code on failure.
>   */
>  static int gen8_append_oa_reports(struct i915_perf_stream *stream,
>  				  char __user *buf,
> @@ -900,41 +901,42 @@ static int gen8_oa_read(struct i915_perf_stream *stream,
>  		/*
>  		 * Note: .oa_enable() is expected to re-init the oabuffer and
>  		 * reset GEN8_OASTATUS for us
>  		 */
>  		oastatus = intel_uncore_read(uncore, oastatus_reg);
>  	}
>  
>  	if (oastatus & GEN8_OASTATUS_REPORT_LOST) {
>  		ret = append_oa_status(stream, buf, count, offset,
>  				       DRM_I915_PERF_RECORD_OA_REPORT_LOST);
>  		if (ret)
>  			return ret;
>  		intel_uncore_write(uncore, oastatus_reg,
>  				   oastatus & ~GEN8_OASTATUS_REPORT_LOST);
>  	}
>  
>  	return gen8_append_oa_reports(stream, buf, count, offset);
>  }
>  
>  /**
> - * Copies all buffered OA reports into userspace read() buffer.
> + * gen7_append_oa_reports - Copies all buffered OA reports into
> + *			    userspace read() buffer.
>   * @stream: An i915-perf stream opened for OA metrics
>   * @buf: destination buffer given by userspace
>   * @count: the number of bytes userspace wants to read
>   * @offset: (inout): the current position for writing into @buf
>   *
>   * Notably any error condition resulting in a short read (-%ENOSPC or
>   * -%EFAULT) will be returned even though one or more records may
>   * have been successfully copied. In this case it's up to the caller
>   * to decide if the error should be squashed before returning to
>   * userspace.
>   *
>   * Note: reports are consumed from the head, and appended to the
>   * tail, so the tail chases the head?... If you think that's mad
>   * and back-to-front you're not alone, but this follows the
>   * Gen PRM naming convention.
>   *
>   * Returns: 0 on success, negative error code on failure.
>   */
>  static int gen7_append_oa_reports(struct i915_perf_stream *stream,
>  				  char __user *buf,
> @@ -3210,41 +3212,41 @@ static long i915_perf_config_locked(struct i915_perf_stream *stream,
>  		 * reconfiguration inline from that context. The update
>  		 * will then be ordered with respect to submission on that
>  		 * context.
>  		 *
>  		 * When set globally, we use a low priority kernel context,
>  		 * so it will effectively take effect when idle.
>  		 */
>  		err = emit_oa_config(stream, config, oa_context(stream), NULL);
>  		if (!err)
>  			config = xchg(&stream->oa_config, config);
>  		else
>  			ret = err;
>  	}
>  
>  	i915_oa_config_put(config);
>  
>  	return ret;
>  }
>  
>  /**
> - * i915_perf_ioctl - support ioctl() usage with i915 perf stream FDs
> + * i915_perf_ioctl_locked - support ioctl() usage with i915 perf stream FDs
>   * @stream: An i915 perf stream
>   * @cmd: the ioctl request
>   * @arg: the ioctl data
>   *
>   * Note: The &perf->lock mutex has been taken to serialize
>   * with any non-file-operation driver hooks.
>   *
>   * Returns: zero on success or a negative error code. Returns -EINVAL for
>   * an unknown ioctl request.
>   */
>  static long i915_perf_ioctl_locked(struct i915_perf_stream *stream,
>  				   unsigned int cmd,
>  				   unsigned long arg)
>  {
>  	switch (cmd) {
>  	case I915_PERF_IOCTL_ENABLE:
>  		i915_perf_enable_locked(stream);
>  		return 0;
>  	case I915_PERF_IOCTL_DISABLE:
>  		i915_perf_disable_locked(stream);
> diff --git a/drivers/gpu/drm/scheduler/sched_main.c b/drivers/gpu/drm/scheduler/sched_main.c
> index da24c4e8b9fb..b498d474ef9e 100644
> --- a/drivers/gpu/drm/scheduler/sched_main.c
> +++ b/drivers/gpu/drm/scheduler/sched_main.c
> @@ -430,41 +430,41 @@ void drm_sched_stop(struct drm_gpu_scheduler *sched, struct drm_sched_job *bad)
>  			 */
>  			if (bad != s_job)
>  				sched->ops->free_job(s_job);
>  			else
>  				sched->free_guilty = true;
>  		}
>  	}
>  
>  	/*
>  	 * Stop pending timer in flight as we rearm it in  drm_sched_start. This
>  	 * avoids the pending timeout work in progress to fire right away after
>  	 * this TDR finished and before the newly restarted jobs had a
>  	 * chance to complete.
>  	 */
>  	cancel_delayed_work(&sched->work_tdr);
>  }
>  
>  EXPORT_SYMBOL(drm_sched_stop);
>  
>  /**
> - * drm_sched_job_recovery - recover jobs after a reset
> + * drm_sched_start - recover jobs after a reset
>   *
>   * @sched: scheduler instance
>   * @full_recovery: proceed with complete sched restart
>   *
>   */
>  void drm_sched_start(struct drm_gpu_scheduler *sched, bool full_recovery)
>  {
>  	struct drm_sched_job *s_job, *tmp;
>  	int r;
>  
>  	/*
>  	 * Locking the list is not required here as the sched thread is parked
>  	 * so no new jobs are being inserted or removed. Also concurrent
>  	 * GPU recovers can't run in parallel.
>  	 */
>  	list_for_each_entry_safe(s_job, tmp, &sched->ring_mirror_list, node) {
>  		struct dma_fence *fence = s_job->s_fence->parent;
>  
>  		atomic_inc(&sched->hw_rq_count);
>  
> diff --git a/drivers/gpu/drm/v3d/v3d_sched.c b/drivers/gpu/drm/v3d/v3d_sched.c
> index 0747614a78f0..f968f389633a 100644
> --- a/drivers/gpu/drm/v3d/v3d_sched.c
> +++ b/drivers/gpu/drm/v3d/v3d_sched.c
> @@ -47,41 +47,41 @@ to_tfu_job(struct drm_sched_job *sched_job)
>  {
>  	return container_of(sched_job, struct v3d_tfu_job, base.base);
>  }
>  
>  static struct v3d_csd_job *
>  to_csd_job(struct drm_sched_job *sched_job)
>  {
>  	return container_of(sched_job, struct v3d_csd_job, base.base);
>  }
>  
>  static void
>  v3d_job_free(struct drm_sched_job *sched_job)
>  {
>  	struct v3d_job *job = to_v3d_job(sched_job);
>  
>  	drm_sched_job_cleanup(sched_job);
>  	v3d_job_put(job);
>  }
>  
>  /**
> - * Returns the fences that the job depends on, one by one.
> + * v3d_job_dependency - Returns the fences that the job depends on, one by one.
>   *
>   * If placed in the scheduler's .dependency method, the corresponding
>   * .run_job won't be called until all of them have been signaled.
>   */
>  static struct dma_fence *
>  v3d_job_dependency(struct drm_sched_job *sched_job,
>  		   struct drm_sched_entity *s_entity)
>  {
>  	struct v3d_job *job = to_v3d_job(sched_job);
>  
>  	/* XXX: Wait on a fence for switching the GMP if necessary,
>  	 * and then do so.
>  	 */
>  
>  	if (!xa_empty(&job->deps))
>  		return xa_erase(&job->deps, job->last_dep++);
>  
>  	return NULL;
>  }
>  
> diff --git a/drivers/gpu/drm/vc4/vc4_bo.c b/drivers/gpu/drm/vc4/vc4_bo.c
> index a21a6c53ffcf..469d1b4f2643 100644
> --- a/drivers/gpu/drm/vc4/vc4_bo.c
> +++ b/drivers/gpu/drm/vc4/vc4_bo.c
> @@ -374,41 +374,41 @@ static struct vc4_bo *vc4_bo_get_from_cache(struct drm_device *dev,
>  		vc4_bo_set_label(&bo->base.base, type);
>  	mutex_unlock(&vc4->bo_lock);
>  	return bo;
>  }
>  
>  static const struct vm_operations_struct vc4_vm_ops = {
>  	.fault = vc4_fault,
>  	.open = drm_gem_vm_open,
>  	.close = drm_gem_vm_close,
>  };
>  
>  static const struct drm_gem_object_funcs vc4_gem_object_funcs = {
>  	.free = vc4_free_object,
>  	.export = vc4_prime_export,
>  	.get_sg_table = drm_gem_cma_prime_get_sg_table,
>  	.vmap = vc4_prime_vmap,
>  	.vm_ops = &vc4_vm_ops,
>  };
>  
>  /**
> - * vc4_gem_create_object - Implementation of driver->gem_create_object.
> + * vc4_create_object - Implementation of driver->gem_create_object.
>   * @dev: DRM device
>   * @size: Size in bytes of the memory the object will reference
>   *
>   * This lets the CMA helpers allocate object structs for us, and keep
>   * our BO stats correct.
>   */
>  struct drm_gem_object *vc4_create_object(struct drm_device *dev, size_t size)
>  {
>  	struct vc4_dev *vc4 = to_vc4_dev(dev);
>  	struct vc4_bo *bo;
>  
>  	bo = kzalloc(sizeof(*bo), GFP_KERNEL);
>  	if (!bo)
>  		return ERR_PTR(-ENOMEM);
>  
>  	bo->madv = VC4_MADV_WILLNEED;
>  	refcount_set(&bo->usecnt, 0);
>  	mutex_init(&bo->madv_lock);
>  	mutex_lock(&vc4->bo_lock);
>  	bo->label = VC4_BO_TYPE_KERNEL;
> diff --git a/include/drm/drm_atomic_helper.h b/include/drm/drm_atomic_helper.h
> index 85df04c8e62f..5f47720440fa 100644
> --- a/include/drm/drm_atomic_helper.h
> +++ b/include/drm/drm_atomic_helper.h
> @@ -150,54 +150,54 @@ int drm_atomic_helper_page_flip_target(
>  int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc,
>  				       u16 *red, u16 *green, u16 *blue,
>  				       uint32_t size,
>  				       struct drm_modeset_acquire_ctx *ctx);
>  
>  /**
>   * drm_atomic_crtc_for_each_plane - iterate over planes currently attached to CRTC
>   * @plane: the loop cursor
>   * @crtc:  the CRTC whose planes are iterated
>   *
>   * This iterates over the current state, useful (for example) when applying
>   * atomic state after it has been checked and swapped.  To iterate over the
>   * planes which *will* be attached (more useful in code called from
>   * &drm_mode_config_funcs.atomic_check) see
>   * drm_atomic_crtc_state_for_each_plane().
>   */
>  #define drm_atomic_crtc_for_each_plane(plane, crtc) \
>  	drm_for_each_plane_mask(plane, (crtc)->dev, (crtc)->state->plane_mask)
>  
>  /**
> - * drm_crtc_atomic_state_for_each_plane - iterate over attached planes in new state
> + * drm_atomic_crtc_state_for_each_plane - iterate over attached planes in new state
>   * @plane: the loop cursor
>   * @crtc_state: the incoming CRTC state
>   *
>   * Similar to drm_crtc_for_each_plane(), but iterates the planes that will be
>   * attached if the specified state is applied.  Useful during for example
>   * in code called from &drm_mode_config_funcs.atomic_check operations, to
>   * validate the incoming state.
>   */
>  #define drm_atomic_crtc_state_for_each_plane(plane, crtc_state) \
>  	drm_for_each_plane_mask(plane, (crtc_state)->state->dev, (crtc_state)->plane_mask)
>  
>  /**
> - * drm_crtc_atomic_state_for_each_plane_state - iterate over attached planes in new state
> + * drm_atomic_crtc_state_for_each_plane_state - iterate over attached planes in new state
>   * @plane: the loop cursor
>   * @plane_state: loop cursor for the plane's state, must be const
>   * @crtc_state: the incoming CRTC state
>   *
>   * Similar to drm_crtc_for_each_plane(), but iterates the planes that will be
>   * attached if the specified state is applied.  Useful during for example
>   * in code called from &drm_mode_config_funcs.atomic_check operations, to
>   * validate the incoming state.
>   *
>   * Compared to just drm_atomic_crtc_state_for_each_plane() this also fills in a
>   * const plane_state. This is useful when a driver just wants to peek at other
>   * active planes on this CRTC, but does not need to change it.
>   */
>  #define drm_atomic_crtc_state_for_each_plane_state(plane, plane_state, crtc_state) \
>  	drm_for_each_plane_mask(plane, (crtc_state)->state->dev, (crtc_state)->plane_mask) \
>  		for_each_if ((plane_state = \
>  			      __drm_atomic_get_current_plane_state((crtc_state)->state, \
>  								   plane)))
>  
>  /**
> diff --git a/include/drm/drm_connector.h b/include/drm/drm_connector.h
> index 928136556174..fcdc58d8b88b 100644
> --- a/include/drm/drm_connector.h
> +++ b/include/drm/drm_connector.h
> @@ -67,41 +67,41 @@ enum drm_connector_status {
>  	 * sink device which can be autodetect. For digital outputs like DP or
>  	 * HDMI (which can be realiable probed) this means there's really
>  	 * nothing there. It is driver-dependent whether a connector with this
>  	 * status can be lit up or not.
>  	 */
>  	connector_status_disconnected = 2,
>  	/**
>  	 * @connector_status_unknown: The connector's status could not be
>  	 * reliably detected. This happens when probing would either cause
>  	 * flicker (like load-detection when the connector is in use), or when a
>  	 * hardware resource isn't available (like when load-detection needs a
>  	 * free CRTC). It should be possible to light up the connector with one
>  	 * of the listed fallback modes. For default configuration userspace
>  	 * should only try to light up connectors with unknown status when
>  	 * there's not connector with @connector_status_connected.
>  	 */
>  	connector_status_unknown = 3,
>  };
>  
>  /**
> - * enum drm_connector_registration_status - userspace registration status for
> + * enum drm_connector_registration_state - userspace registration status for
>   * a &drm_connector
>   *
>   * This enum is used to track the status of initializing a connector and
>   * registering it with userspace, so that DRM can prevent bogus modesets on
>   * connectors that no longer exist.
>   */
>  enum drm_connector_registration_state {
>  	/**
>  	 * @DRM_CONNECTOR_INITIALIZING: The connector has just been created,
>  	 * but has yet to be exposed to userspace. There should be no
>  	 * additional restrictions to how the state of this connector may be
>  	 * modified.
>  	 */
>  	DRM_CONNECTOR_INITIALIZING = 0,
>  
>  	/**
>  	 * @DRM_CONNECTOR_REGISTERED: The connector has been fully initialized
>  	 * and registered with sysfs, as such it has been exposed to
>  	 * userspace. There should be no additional restrictions to how the
>  	 * state of this connector may be modified.
> diff --git a/include/drm/drm_device.h b/include/drm/drm_device.h
> index 2c361964aee7..283a93ce4617 100644
> --- a/include/drm/drm_device.h
> +++ b/include/drm/drm_device.h
> @@ -10,41 +10,41 @@
>  #include <drm/drm_mode_config.h>
>  
>  struct drm_driver;
>  struct drm_minor;
>  struct drm_master;
>  struct drm_device_dma;
>  struct drm_vblank_crtc;
>  struct drm_sg_mem;
>  struct drm_local_map;
>  struct drm_vma_offset_manager;
>  struct drm_vram_mm;
>  struct drm_fb_helper;
>  
>  struct inode;
>  
>  struct pci_dev;
>  struct pci_controller;
>  
>  
>  /**
> - * enum drm_switch_power - power state of drm device
> + * enum switch_power_state - power state of drm device
>   */
>  
>  enum switch_power_state {
>  	/** @DRM_SWITCH_POWER_ON: Power state is ON */
>  	DRM_SWITCH_POWER_ON = 0,
>  
>  	/** @DRM_SWITCH_POWER_OFF: Power state is OFF */
>  	DRM_SWITCH_POWER_OFF = 1,
>  
>  	/** @DRM_SWITCH_POWER_CHANGING: Power state is changing */
>  	DRM_SWITCH_POWER_CHANGING = 2,
>  
>  	/** @DRM_SWITCH_POWER_DYNAMIC_OFF: Suspended */
>  	DRM_SWITCH_POWER_DYNAMIC_OFF = 3,
>  };
>  
>  /**
>   * struct drm_device - DRM device structure
>   *
>   * This structure represent a complete card that
> diff --git a/include/drm/drm_dsc.h b/include/drm/drm_dsc.h
> index 732f32740c86..53c51231b31c 100644
> --- a/include/drm/drm_dsc.h
> +++ b/include/drm/drm_dsc.h
> @@ -256,41 +256,42 @@ struct drm_dsc_config {
>  	bool native_420;
>  	/**
>  	 * @second_line_bpg_offset:
>  	 * Additional bits/grp for seconnd line of slice for native 4:2:0
>  	 */
>  	u8 second_line_bpg_offset;
>  	/**
>  	 * @nsl_bpg_offset:
>  	 * Num of bits deallocated for each grp that is not in second line of
>  	 * slice
>  	 */
>  	u16 nsl_bpg_offset;
>  	/**
>  	 * @second_line_offset_adj:
>  	 * Offset adjustment for second line in Native 4:2:0 mode
>  	 */
>  	u16 second_line_offset_adj;
>  };
>  
>  /**
> - * struct picture_parameter_set - Represents 128 bytes of Picture Parameter Set
> + * struct drm_dsc_picture_parameter_set - Represents 128 bytes of
> + * 	Picture Parameter Set
>   *
>   * The VESA DSC standard defines picture parameter set (PPS) which display
>   * stream compression encoders must communicate to decoders.
>   * The PPS is encapsulated in 128 bytes (PPS 0 through PPS 127). The fields in
>   * this structure are as per Table 4.1 in Vesa DSC specification v1.1/v1.2.
>   * The PPS fields that span over more than a byte should be stored in Big Endian
>   * format.
>   */
>  struct drm_dsc_picture_parameter_set {
>  	/**
>  	 * @dsc_version:
>  	 * PPS0[3:0] - dsc_version_minor: Contains Minor version of DSC
>  	 * PPS0[7:4] - dsc_version_major: Contains major version of DSC
>  	 */
>  	u8 dsc_version;
>  	/**
>  	 * @pps_identifier:
>  	 * PPS1[7:0] - Application specific identifier that can be
>  	 * used to differentiate between different PPS tables.
>  	 */
> diff --git a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h
> index c0d28ba0f5c9..a4bac02249c2 100644
> --- a/include/drm/drm_gem_vram_helper.h
> +++ b/include/drm/drm_gem_vram_helper.h
> @@ -49,54 +49,54 @@ struct vm_area_struct;
>   * drm_gem_vram_vmap() and drm_gem_vram_vunmap().
>   */
>  struct drm_gem_vram_object {
>  	struct ttm_buffer_object bo;
>  	struct dma_buf_map map;
>  
>  	/**
>  	 * @vmap_use_count:
>  	 *
>  	 * Reference count on the virtual address.
>  	 * The address are un-mapped when the count reaches zero.
>  	 */
>  	unsigned int vmap_use_count;
>  
>  	/* Supported placements are %TTM_PL_VRAM and %TTM_PL_SYSTEM */
>  	struct ttm_placement placement;
>  	struct ttm_place placements[2];
>  };
>  
>  /**
> - * Returns the container of type &struct drm_gem_vram_object
> - * for field bo.
> + * drm_gem_vram_of_bo - Returns the container of type
> + * &struct drm_gem_vram_object for field bo.
>   * @bo:		the VRAM buffer object
>   * Returns:	The containing GEM VRAM object
>   */
>  static inline struct drm_gem_vram_object *drm_gem_vram_of_bo(
>  	struct ttm_buffer_object *bo)
>  {
>  	return container_of(bo, struct drm_gem_vram_object, bo);
>  }
>  
>  /**
> - * Returns the container of type &struct drm_gem_vram_object
> - * for field gem.
> + * drm_gem_vram_of_gem - Returns the container of type
> + * &struct drm_gem_vram_object for field gem.
>   * @gem:	the GEM object
>   * Returns:	The containing GEM VRAM object
>   */
>  static inline struct drm_gem_vram_object *drm_gem_vram_of_gem(
>  	struct drm_gem_object *gem)
>  {
>  	return container_of(gem, struct drm_gem_vram_object, bo.base);
>  }
>  
>  struct drm_gem_vram_object *drm_gem_vram_create(struct drm_device *dev,
>  						size_t size,
>  						unsigned long pg_align);
>  void drm_gem_vram_put(struct drm_gem_vram_object *gbo);
>  u64 drm_gem_vram_mmap_offset(struct drm_gem_vram_object *gbo);
>  s64 drm_gem_vram_offset(struct drm_gem_vram_object *gbo);
>  int drm_gem_vram_pin(struct drm_gem_vram_object *gbo, unsigned long pl_flag);
>  int drm_gem_vram_unpin(struct drm_gem_vram_object *gbo);
>  int drm_gem_vram_vmap(struct drm_gem_vram_object *gbo, struct dma_buf_map *map);
>  void drm_gem_vram_vunmap(struct drm_gem_vram_object *gbo, struct dma_buf_map *map);

-- 
Jani Nikula, Intel Open Source Graphics Center

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 04/27] s390: fix kernel-doc markups
  2020-11-16 10:38   ` Vineeth Vijayan
@ 2020-11-16 12:04     ` Vineeth Vijayan
  0 siblings, 0 replies; 51+ messages in thread
From: Vineeth Vijayan @ 2020-11-16 12:04 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Linux Doc Mailing List
  Cc: Jonathan Corbet, Alexander Egorenkov, Alexandra Winter,
	Christian Borntraeger, Heiko Carstens, Julian Wiedmann,
	Peter Oberparleiter, Sven Schnelle, Vasily Gorbik,
	Vineeth Vijayan, linux-kernel, linux-s390

Heiko/Vasily will pick this up and will be part of the s390-tree patchset.

Regards
Vineeth


On 11/16/20 11:38 AM, Vineeth Vijayan wrote:
> Thank you very much for the fix.
>
> Reviewed-by: Vineeth Vijayan <vneethv@linux.ibm.com>
>
>
>
> On 11/16/20 11:18 AM, Mauro Carvalho Chehab wrote:
>> fix one typo:
>>     ccw driver -> ccw_driver
>>
>> and one function rename.
>>
>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>> ---
>>   arch/s390/include/asm/ccwdev.h | 2 +-
>>   arch/s390/include/asm/cio.h    | 2 +-
>>   2 files changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/arch/s390/include/asm/ccwdev.h 
>> b/arch/s390/include/asm/ccwdev.h
>> index bf605e1fcf6a..0495ac635ed5 100644
>> --- a/arch/s390/include/asm/ccwdev.h
>> +++ b/arch/s390/include/asm/ccwdev.h
>> @@ -100,41 +100,41 @@ struct ccw_device {
>>    */
>>   #define PE_NONE                0x0
>>   #define PE_PATH_GONE            0x1 /* A path is no longer 
>> available. */
>>   #define PE_PATH_AVAILABLE        0x2 /* A path has become available 
>> and
>>                              was successfully verified. */
>>   #define PE_PATHGROUP_ESTABLISHED    0x4 /* A pathgroup was reset 
>> and had
>>                              to be established again. */
>>   #define PE_PATH_FCES_EVENT        0x8 /* The FCES Status of a path has
>>                            * changed. */
>>     /*
>>    * Possible CIO actions triggered by the unit check handler.
>>    */
>>   enum uc_todo {
>>       UC_TODO_RETRY,
>>       UC_TODO_RETRY_ON_NEW_PATH,
>>       UC_TODO_STOP
>>   };
>>     /**
>> - * struct ccw driver - device driver for channel attached devices
>> + * struct ccw_driver - device driver for channel attached devices
>>    * @ids: ids supported by this driver
>>    * @probe: function called on probe
>>    * @remove: function called on remove
>>    * @set_online: called when setting device online
>>    * @set_offline: called when setting device offline
>>    * @notify: notify driver of device state changes
>>    * @path_event: notify driver of channel path events
>>    * @shutdown: called at device shutdown
>>    * @prepare: prepare for pm state transition
>>    * @complete: undo work done in @prepare
>>    * @freeze: callback for freezing during hibernation snapshotting
>>    * @thaw: undo work done in @freeze
>>    * @restore: callback for restoring after hibernation
>>    * @uc_handler: callback for unit check handler
>>    * @driver: embedded device driver structure
>>    * @int_class: interruption class to use for accounting interrupts
>>    */
>>   struct ccw_driver {
>>       struct ccw_device_id *ids;
>>       int (*probe) (struct ccw_device *);
>> diff --git a/arch/s390/include/asm/cio.h b/arch/s390/include/asm/cio.h
>> index e36cb67d2441..ac02df906cae 100644
>> --- a/arch/s390/include/asm/cio.h
>> +++ b/arch/s390/include/asm/cio.h
>> @@ -312,41 +312,41 @@ struct node_descriptor {
>>   /* Device did not respond in time. */
>>   #define CIO_BOXED      0x0010
>>     /**
>>    * struct ccw_dev_id - unique identifier for ccw devices
>>    * @ssid: subchannel set id
>>    * @devno: device number
>>    *
>>    * This structure is not directly based on any hardware structure. The
>>    * hardware identifies a device by its device number and its 
>> subchannel,
>>    * which is in turn identified by its id. In order to get a unique 
>> identifier
>>    * for ccw devices across subchannel sets, @struct ccw_dev_id has been
>>    * introduced.
>>    */
>>   struct ccw_dev_id {
>>       u8 ssid;
>>       u16 devno;
>>   };
>>     /**
>> - * ccw_device_id_is_equal() - compare two ccw_dev_ids
>> + * ccw_dev_id_is_equal() - compare two ccw_dev_ids
>>    * @dev_id1: a ccw_dev_id
>>    * @dev_id2: another ccw_dev_id
>>    * Returns:
>>    *  %1 if the two structures are equal field-by-field,
>>    *  %0 if not.
>>    * Context:
>>    *  any
>>    */
>>   static inline int ccw_dev_id_is_equal(struct ccw_dev_id *dev_id1,
>>                         struct ccw_dev_id *dev_id2)
>>   {
>>       if ((dev_id1->ssid == dev_id2->ssid) &&
>>           (dev_id1->devno == dev_id2->devno))
>>           return 1;
>>       return 0;
>>   }
>>     /**
>>    * pathmask_to_pos() - find the position of the left-most bit in a 
>> pathmask
>>    * @mask: pathmask with at least one bit set

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 24/27] shed: fix kernel-doc markup
  2020-11-16 10:18 ` [PATCH v4 24/27] shed: fix kernel-doc markup Mauro Carvalho Chehab
@ 2020-11-16 12:34   ` Vincent Guittot
  0 siblings, 0 replies; 51+ messages in thread
From: Vincent Guittot @ 2020-11-16 12:34 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Ingo Molnar, Juri Lelli, Peter Zijlstra, Jonathan Corbet,
	Linux Doc Mailing List, Ben Segall, Daniel Bristot de Oliveira,
	Dietmar Eggemann, Mel Gorman, Steven Rostedt, linux-kernel

On Mon, 16 Nov 2020 at 11:18, Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>

s/shed/sched

> Kernel-doc requires that a kernel-doc markup to be immediatly

s/immediatly/immediately

> below the function prototype, as otherwise it will rename it.
> So, move sys_sched_yield() markup to the right place.
>
> Also fix the cpu_util() markup: Kernel-doc markups
> should use this format:
>         identifier - description
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Reviewed-by: Vincent Guittot <vincent.guittot@linaro.org>

> ---
>  kernel/sched/core.c | 16 ++++++++--------
>  kernel/sched/fair.c |  2 +-
>  2 files changed, 9 insertions(+), 9 deletions(-)
>
> diff --git a/kernel/sched/core.c b/kernel/sched/core.c
> index 02076e6d3792..9d41378ae8f3 100644
> --- a/kernel/sched/core.c
> +++ b/kernel/sched/core.c
> @@ -6560,65 +6560,65 @@ SYSCALL_DEFINE3(sched_getaffinity, pid_t, pid, unsigned int, len,
>         if (len & (sizeof(unsigned long)-1))
>                 return -EINVAL;
>
>         if (!alloc_cpumask_var(&mask, GFP_KERNEL))
>                 return -ENOMEM;
>
>         ret = sched_getaffinity(pid, mask);
>         if (ret == 0) {
>                 unsigned int retlen = min(len, cpumask_size());
>
>                 if (copy_to_user(user_mask_ptr, mask, retlen))
>                         ret = -EFAULT;
>                 else
>                         ret = retlen;
>         }
>         free_cpumask_var(mask);
>
>         return ret;
>  }
>
> -/**
> - * sys_sched_yield - yield the current processor to other threads.
> - *
> - * This function yields the current CPU to other tasks. If there are no
> - * other threads running on this CPU then this function will return.
> - *
> - * Return: 0.
> - */
>  static void do_sched_yield(void)
>  {
>         struct rq_flags rf;
>         struct rq *rq;
>
>         rq = this_rq_lock_irq(&rf);
>
>         schedstat_inc(rq->yld_count);
>         current->sched_class->yield_task(rq);
>
>         preempt_disable();
>         rq_unlock_irq(rq, &rf);
>         sched_preempt_enable_no_resched();
>
>         schedule();
>  }
>
> +/**
> + * sys_sched_yield - yield the current processor to other threads.
> + *
> + * This function yields the current CPU to other tasks. If there are no
> + * other threads running on this CPU then this function will return.
> + *
> + * Return: 0.
> + */
>  SYSCALL_DEFINE0(sched_yield)
>  {
>         do_sched_yield();
>         return 0;
>  }
>
>  #ifndef CONFIG_PREEMPTION
>  int __sched _cond_resched(void)
>  {
>         if (should_resched(0)) {
>                 preempt_schedule_common();
>                 return 1;
>         }
>         rcu_all_qs();
>         return 0;
>  }
>  EXPORT_SYMBOL(_cond_resched);
>  #endif
>
>  /*
> diff --git a/kernel/sched/fair.c b/kernel/sched/fair.c
> index 27536f37ba1a..cb7cd7d8a28f 100644
> --- a/kernel/sched/fair.c
> +++ b/kernel/sched/fair.c
> @@ -6310,41 +6310,41 @@ static int select_idle_sibling(struct task_struct *p, int prev, int target)
>         sd = rcu_dereference(per_cpu(sd_llc, target));
>         if (!sd)
>                 return target;
>
>         i = select_idle_core(p, sd, target);
>         if ((unsigned)i < nr_cpumask_bits)
>                 return i;
>
>         i = select_idle_cpu(p, sd, target);
>         if ((unsigned)i < nr_cpumask_bits)
>                 return i;
>
>         i = select_idle_smt(p, sd, target);
>         if ((unsigned)i < nr_cpumask_bits)
>                 return i;
>
>         return target;
>  }
>
>  /**
> - * Amount of capacity of a CPU that is (estimated to be) used by CFS tasks
> + * cpu_util - Estimates the amount of capacity of a CPU used by CFS tasks.
>   * @cpu: the CPU to get the utilization of
>   *
>   * The unit of the return value must be the one of capacity so we can compare
>   * the utilization with the capacity of the CPU that is available for CFS task
>   * (ie cpu_capacity).
>   *
>   * cfs_rq.avg.util_avg is the sum of running time of runnable tasks plus the
>   * recent utilization of currently non-runnable tasks on a CPU. It represents
>   * the amount of utilization of a CPU in the range [0..capacity_orig] where
>   * capacity_orig is the cpu_capacity available at the highest frequency
>   * (arch_scale_freq_capacity()).
>   * The utilization of a CPU converges towards a sum equal to or less than the
>   * current capacity (capacity_curr <= capacity_orig) of the CPU because it is
>   * the running time on this CPU scaled by capacity_curr.
>   *
>   * The estimated utilization of a CPU is defined to be the maximum between its
>   * cfs_rq.avg.util_avg and the sum of the estimated utilization of the tasks
>   * currently RUNNABLE on that CPU.
>   * This allows to properly represent the expected utilization of a CPU which
>   * has just got a big task running since a long sleep period. At the same time
> --
> 2.28.0
>

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 27/27] scripts: kernel-doc: validate kernel-doc markup with the actual names
  2020-11-16 10:18 ` [PATCH v4 27/27] scripts: kernel-doc: validate kernel-doc markup with the actual names Mauro Carvalho Chehab
@ 2020-11-16 15:06   ` kernel test robot
  2020-11-16 15:42   ` kernel test robot
  2020-11-16 15:51   ` kernel test robot
  2 siblings, 0 replies; 51+ messages in thread
From: kernel test robot @ 2020-11-16 15:06 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Jonathan Corbet
  Cc: kbuild-all, linux-media, Mauro Carvalho Chehab,
	Linux Doc Mailing List, linux-kernel

[-- Attachment #1: Type: text/plain, Size: 4717 bytes --]

Hi Mauro,

I love your patch! Perhaps something to improve:

[auto build test WARNING on next-20201116]
[cannot apply to drm-intel/for-linux-next s390/features tip/timers/core tip/irq/core tip/sched/core linus/master hnaz-linux-mm/master v5.10-rc4 v5.10-rc3 v5.10-rc2 v5.10-rc4]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch]

url:    https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/net-phy-fix-kernel-doc-markups/20201116-191847
base:    034307507118f7e1b18f8403c85af2216da2dc94
config: nios2-randconfig-r022-20201116 (attached as .config)
compiler: nios2-linux-gcc (GCC) 9.3.0
reproduce (this is a W=1 build):
        wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
        chmod +x ~/bin/make.cross
        # https://github.com/0day-ci/linux/commit/11cd9cdaab434fff7a5edbee8d8d4ce9ef11acf4
        git remote add linux-review https://github.com/0day-ci/linux
        git fetch --no-tags linux-review Mauro-Carvalho-Chehab/net-phy-fix-kernel-doc-markups/20201116-191847
        git checkout 11cd9cdaab434fff7a5edbee8d8d4ce9ef11acf4
        # save the attached .config to linux build tree
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-9.3.0 make.cross ARCH=nios2 

If you fix the issue, kindly add following tag as appropriate
Reported-by: kernel test robot <lkp@intel.com>

All warnings (new ones prefixed by >>):

>> net/batman-adv/multicast.c:840: warning: expecting prototype for batadv_mcast_flags_logs(). Prototype was for batadv_mcast_flags_log() instead

vim +840 net/batman-adv/multicast.c

72f7b2deafde895 Linus Lüssing  2016-05-10  830  
72f7b2deafde895 Linus Lüssing  2016-05-10  831  /**
7e9a8c2ce7c5f87 Sven Eckelmann 2017-12-02  832   * batadv_mcast_flags_logs() - output debug information about mcast flag changes
72f7b2deafde895 Linus Lüssing  2016-05-10  833   * @bat_priv: the bat priv with all the soft interface information
6bc4544021f8228 Linus Lüssing  2019-05-07  834   * @flags: TVLV flags indicating the new multicast state
72f7b2deafde895 Linus Lüssing  2016-05-10  835   *
bccb48c89fe3c09 Sven Eckelmann 2020-06-01  836   * Whenever the multicast TVLV flags this node announces change, this function
bccb48c89fe3c09 Sven Eckelmann 2020-06-01  837   * should be used to notify userspace about the change.
72f7b2deafde895 Linus Lüssing  2016-05-10  838   */
72f7b2deafde895 Linus Lüssing  2016-05-10  839  static void batadv_mcast_flags_log(struct batadv_priv *bat_priv, u8 flags)
72f7b2deafde895 Linus Lüssing  2016-05-10 @840  {
6bc4544021f8228 Linus Lüssing  2019-05-07  841  	bool old_enabled = bat_priv->mcast.mla_flags.enabled;
6bc4544021f8228 Linus Lüssing  2019-05-07  842  	u8 old_flags = bat_priv->mcast.mla_flags.tvlv_flags;
61caf3d109f5411 Linus Lüssing  2019-06-11  843  	char str_old_flags[] = "[.... . ]";
72f7b2deafde895 Linus Lüssing  2016-05-10  844  
61caf3d109f5411 Linus Lüssing  2019-06-11  845  	sprintf(str_old_flags, "[%c%c%c%s%s]",
72f7b2deafde895 Linus Lüssing  2016-05-10  846  		(old_flags & BATADV_MCAST_WANT_ALL_UNSNOOPABLES) ? 'U' : '.',
72f7b2deafde895 Linus Lüssing  2016-05-10  847  		(old_flags & BATADV_MCAST_WANT_ALL_IPV4) ? '4' : '.',
61caf3d109f5411 Linus Lüssing  2019-06-11  848  		(old_flags & BATADV_MCAST_WANT_ALL_IPV6) ? '6' : '.',
61caf3d109f5411 Linus Lüssing  2019-06-11  849  		!(old_flags & BATADV_MCAST_WANT_NO_RTR4) ? "R4" : ". ",
61caf3d109f5411 Linus Lüssing  2019-06-11  850  		!(old_flags & BATADV_MCAST_WANT_NO_RTR6) ? "R6" : ". ");
72f7b2deafde895 Linus Lüssing  2016-05-10  851  
72f7b2deafde895 Linus Lüssing  2016-05-10  852  	batadv_dbg(BATADV_DBG_MCAST, bat_priv,
61caf3d109f5411 Linus Lüssing  2019-06-11  853  		   "Changing multicast flags from '%s' to '[%c%c%c%s%s]'\n",
6bc4544021f8228 Linus Lüssing  2019-05-07  854  		   old_enabled ? str_old_flags : "<undefined>",
72f7b2deafde895 Linus Lüssing  2016-05-10  855  		   (flags & BATADV_MCAST_WANT_ALL_UNSNOOPABLES) ? 'U' : '.',
72f7b2deafde895 Linus Lüssing  2016-05-10  856  		   (flags & BATADV_MCAST_WANT_ALL_IPV4) ? '4' : '.',
61caf3d109f5411 Linus Lüssing  2019-06-11  857  		   (flags & BATADV_MCAST_WANT_ALL_IPV6) ? '6' : '.',
61caf3d109f5411 Linus Lüssing  2019-06-11  858  		   !(flags & BATADV_MCAST_WANT_NO_RTR4) ? "R4" : ". ",
61caf3d109f5411 Linus Lüssing  2019-06-11  859  		   !(flags & BATADV_MCAST_WANT_NO_RTR6) ? "R6" : ". ");
72f7b2deafde895 Linus Lüssing  2016-05-10  860  }
72f7b2deafde895 Linus Lüssing  2016-05-10  861  

---
0-DAY CI Kernel Test Service, Intel Corporation
https://lists.01.org/hyperkitty/list/kbuild-all@lists.01.org

[-- Attachment #2: .config.gz --]
[-- Type: application/gzip, Size: 21051 bytes --]

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 10/27] video: fix some kernel-doc markups
  2020-11-16 10:18 ` [PATCH v4 10/27] video: fix some kernel-doc markups Mauro Carvalho Chehab
@ 2020-11-16 15:36   ` Daniel Vetter
  2020-11-16 16:38     ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 51+ messages in thread
From: Daniel Vetter @ 2020-11-16 15:36 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Jonathan Corbet,
	Bartlomiej Zolnierkiewicz, Bernard Zhao, Boris Brezillon,
	Daniel Vetter, Gwan-gyeong Mun, Laurent Pinchart, Sam Ravnborg,
	Sebastian Reichel, Thomas Zimmermann, dri-devel, linux-fbdev,
	linux-kernel

On Mon, Nov 16, 2020 at 11:18:06AM +0100, 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>

Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>

I'm assuming you're sending a pull request for this.
-Daniel

> ---
>  drivers/video/fbdev/core/fbcmap.c | 2 +-
>  drivers/video/hdmi.c              | 3 ++-
>  2 files changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/video/fbdev/core/fbcmap.c b/drivers/video/fbdev/core/fbcmap.c
> index e5ae33c1a8e8..757d5c3f620b 100644
> --- a/drivers/video/fbdev/core/fbcmap.c
> +++ b/drivers/video/fbdev/core/fbcmap.c
> @@ -59,41 +59,41 @@ static u16 blue16[] __read_mostly = {
>      0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa,
>      0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff
>  };
>  
>  static const struct fb_cmap default_2_colors = {
>      .len=2, .red=red2, .green=green2, .blue=blue2
>  };
>  static const struct fb_cmap default_8_colors = {
>      .len=8, .red=red8, .green=green8, .blue=blue8
>  };
>  static const struct fb_cmap default_4_colors = {
>      .len=4, .red=red4, .green=green4, .blue=blue4
>  };
>  static const struct fb_cmap default_16_colors = {
>      .len=16, .red=red16, .green=green16, .blue=blue16
>  };
>  
>  
>  
>  /**
> - *	fb_alloc_cmap - allocate a colormap
> + *	fb_alloc_cmap_gfp - allocate a colormap
>   *	@cmap: frame buffer colormap structure
>   *	@len: length of @cmap
>   *	@transp: boolean, 1 if there is transparency, 0 otherwise
>   *	@flags: flags for kmalloc memory allocation
>   *
>   *	Allocates memory for a colormap @cmap.  @len is the
>   *	number of entries in the palette.
>   *
>   *	Returns negative errno on error, or zero on success.
>   *
>   */
>  
>  int fb_alloc_cmap_gfp(struct fb_cmap *cmap, int len, int transp, gfp_t flags)
>  {
>  	int size = len * sizeof(u16);
>  	int ret = -ENOMEM;
>  
>  	flags |= __GFP_NOWARN;
>  
>  	if (cmap->len != len) {
> diff --git a/drivers/video/hdmi.c b/drivers/video/hdmi.c
> index 1e4cb63d0d11..947be761dfa4 100644
> --- a/drivers/video/hdmi.c
> +++ b/drivers/video/hdmi.c
> @@ -1675,41 +1675,42 @@ static int hdmi_audio_infoframe_unpack(struct hdmi_audio_infoframe *frame,
>  
>  	ret = hdmi_audio_infoframe_init(frame);
>  	if (ret)
>  		return ret;
>  
>  	ptr += HDMI_INFOFRAME_HEADER_SIZE;
>  
>  	frame->channels = ptr[0] & 0x7;
>  	frame->coding_type = (ptr[0] >> 4) & 0xf;
>  	frame->sample_size = ptr[1] & 0x3;
>  	frame->sample_frequency = (ptr[1] >> 2) & 0x7;
>  	frame->coding_type_ext = ptr[2] & 0x1f;
>  	frame->channel_allocation = ptr[3];
>  	frame->level_shift_value = (ptr[4] >> 3) & 0xf;
>  	frame->downmix_inhibit = ptr[4] & 0x80 ? true : false;
>  
>  	return 0;
>  }
>  
>  /**
> - * hdmi_vendor_infoframe_unpack() - unpack binary buffer to a HDMI vendor infoframe
> + * hdmi_vendor_any_infoframe_unpack() - unpack binary buffer to a HDMI
> + * 	vendor infoframe
>   * @frame: HDMI Vendor infoframe
>   * @buffer: source buffer
>   * @size: size of buffer
>   *
>   * Unpacks the information contained in binary @buffer into a structured
>   * @frame of the HDMI Vendor information frame.
>   * Also verifies the checksum as required by section 5.3.5 of the HDMI 1.4
>   * specification.
>   *
>   * Returns 0 on success or a negative error code on failure.
>   */
>  static int
>  hdmi_vendor_any_infoframe_unpack(union hdmi_vendor_any_infoframe *frame,
>  				 const void *buffer, size_t size)
>  {
>  	const u8 *ptr = buffer;
>  	size_t length;
>  	int ret;
>  	u8 hdmi_video_format;
>  	struct hdmi_vendor_infoframe *hvf = &frame->hdmi;
> -- 
> 2.28.0
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 27/27] scripts: kernel-doc: validate kernel-doc markup with the actual names
  2020-11-16 10:18 ` [PATCH v4 27/27] scripts: kernel-doc: validate kernel-doc markup with the actual names Mauro Carvalho Chehab
  2020-11-16 15:06   ` kernel test robot
@ 2020-11-16 15:42   ` kernel test robot
  2020-11-16 15:51   ` kernel test robot
  2 siblings, 0 replies; 51+ messages in thread
From: kernel test robot @ 2020-11-16 15:42 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Jonathan Corbet
  Cc: kbuild-all, clang-built-linux, linux-media,
	Mauro Carvalho Chehab, Linux Doc Mailing List, linux-kernel

[-- Attachment #1: Type: text/plain, Size: 11019 bytes --]

Hi Mauro,

I love your patch! Perhaps something to improve:

[auto build test WARNING on next-20201116]
[cannot apply to drm-intel/for-linux-next s390/features tip/timers/core tip/irq/core tip/sched/core linus/master hnaz-linux-mm/master v5.10-rc4 v5.10-rc3 v5.10-rc2 v5.10-rc4]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch]

url:    https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/net-phy-fix-kernel-doc-markups/20201116-191847
base:    034307507118f7e1b18f8403c85af2216da2dc94
config: arm-randconfig-r006-20201116 (attached as .config)
compiler: clang version 12.0.0 (https://github.com/llvm/llvm-project c044709b8fbea2a9a375e4173a6bd735f6866c0c)
reproduce (this is a W=1 build):
        wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
        chmod +x ~/bin/make.cross
        # install arm cross compiling tool for clang build
        # apt-get install binutils-arm-linux-gnueabi
        # https://github.com/0day-ci/linux/commit/11cd9cdaab434fff7a5edbee8d8d4ce9ef11acf4
        git remote add linux-review https://github.com/0day-ci/linux
        git fetch --no-tags linux-review Mauro-Carvalho-Chehab/net-phy-fix-kernel-doc-markups/20201116-191847
        git checkout 11cd9cdaab434fff7a5edbee8d8d4ce9ef11acf4
        # save the attached .config to linux build tree
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=clang make.cross ARCH=arm 

If you fix the issue, kindly add following tag as appropriate
Reported-by: kernel test robot <lkp@intel.com>

All warnings (new ones prefixed by >>):

   arch/arm/common/locomo.c:369: warning: Function parameter or member 'me' not described in '__locomo_probe'
   arch/arm/common/locomo.c:369: warning: Function parameter or member 'mem' not described in '__locomo_probe'
   arch/arm/common/locomo.c:369: warning: Function parameter or member 'irq' not described in '__locomo_probe'
>> arch/arm/common/locomo.c:369: warning: expecting prototype for locomo_probe(). Prototype was for __locomo_probe() instead

vim +369 arch/arm/common/locomo.c

b38d950d3aedf90 John Lenz         2005-09-08  353  
4ebf2d00260bac5 Pavel Machek      2006-03-15  354  
^1da177e4c3f415 Linus Torvalds    2005-04-16  355  /**
^1da177e4c3f415 Linus Torvalds    2005-04-16  356   *	locomo_probe - probe for a single LoCoMo chip.
^1da177e4c3f415 Linus Torvalds    2005-04-16  357   *	@phys_addr: physical address of device.
^1da177e4c3f415 Linus Torvalds    2005-04-16  358   *
^1da177e4c3f415 Linus Torvalds    2005-04-16  359   *	Probe for a LoCoMo chip.  This must be called
^1da177e4c3f415 Linus Torvalds    2005-04-16  360   *	before any other locomo-specific code.
^1da177e4c3f415 Linus Torvalds    2005-04-16  361   *
^1da177e4c3f415 Linus Torvalds    2005-04-16  362   *	Returns:
^1da177e4c3f415 Linus Torvalds    2005-04-16  363   *	%-ENODEV	device not found.
^1da177e4c3f415 Linus Torvalds    2005-04-16  364   *	%-EBUSY		physical address already marked in-use.
^1da177e4c3f415 Linus Torvalds    2005-04-16  365   *	%0		successful.
^1da177e4c3f415 Linus Torvalds    2005-04-16  366   */
^1da177e4c3f415 Linus Torvalds    2005-04-16  367  static int
^1da177e4c3f415 Linus Torvalds    2005-04-16  368  __locomo_probe(struct device *me, struct resource *mem, int irq)
^1da177e4c3f415 Linus Torvalds    2005-04-16 @369  {
ac609d266e4af4e Eric Miao         2010-02-04  370  	struct locomo_platform_data *pdata = me->platform_data;
^1da177e4c3f415 Linus Torvalds    2005-04-16  371  	struct locomo *lchip;
^1da177e4c3f415 Linus Torvalds    2005-04-16  372  	unsigned long r;
^1da177e4c3f415 Linus Torvalds    2005-04-16  373  	int i, ret = -ENODEV;
^1da177e4c3f415 Linus Torvalds    2005-04-16  374  
d2a02b93cf78205 Russell King      2006-03-20  375  	lchip = kzalloc(sizeof(struct locomo), GFP_KERNEL);
^1da177e4c3f415 Linus Torvalds    2005-04-16  376  	if (!lchip)
^1da177e4c3f415 Linus Torvalds    2005-04-16  377  		return -ENOMEM;
^1da177e4c3f415 Linus Torvalds    2005-04-16  378  
^1da177e4c3f415 Linus Torvalds    2005-04-16  379  	spin_lock_init(&lchip->lock);
^1da177e4c3f415 Linus Torvalds    2005-04-16  380  
^1da177e4c3f415 Linus Torvalds    2005-04-16  381  	lchip->dev = me;
^1da177e4c3f415 Linus Torvalds    2005-04-16  382  	dev_set_drvdata(lchip->dev, lchip);
^1da177e4c3f415 Linus Torvalds    2005-04-16  383  
^1da177e4c3f415 Linus Torvalds    2005-04-16  384  	lchip->phys = mem->start;
^1da177e4c3f415 Linus Torvalds    2005-04-16  385  	lchip->irq = irq;
ac609d266e4af4e Eric Miao         2010-02-04  386  	lchip->irq_base = (pdata) ? pdata->irq_base : NO_IRQ;
^1da177e4c3f415 Linus Torvalds    2005-04-16  387  
^1da177e4c3f415 Linus Torvalds    2005-04-16  388  	/*
^1da177e4c3f415 Linus Torvalds    2005-04-16  389  	 * Map the whole region.  This also maps the
^1da177e4c3f415 Linus Torvalds    2005-04-16  390  	 * registers for our children.
^1da177e4c3f415 Linus Torvalds    2005-04-16  391  	 */
^1da177e4c3f415 Linus Torvalds    2005-04-16  392  	lchip->base = ioremap(mem->start, PAGE_SIZE);
^1da177e4c3f415 Linus Torvalds    2005-04-16  393  	if (!lchip->base) {
^1da177e4c3f415 Linus Torvalds    2005-04-16  394  		ret = -ENOMEM;
^1da177e4c3f415 Linus Torvalds    2005-04-16  395  		goto out;
^1da177e4c3f415 Linus Torvalds    2005-04-16  396  	}
^1da177e4c3f415 Linus Torvalds    2005-04-16  397  
^1da177e4c3f415 Linus Torvalds    2005-04-16  398  	/* locomo initialize */
^1da177e4c3f415 Linus Torvalds    2005-04-16  399  	locomo_writel(0, lchip->base + LOCOMO_ICR);
^1da177e4c3f415 Linus Torvalds    2005-04-16  400  	/* KEYBOARD */
^1da177e4c3f415 Linus Torvalds    2005-04-16  401  	locomo_writel(0, lchip->base + LOCOMO_KEYBOARD + LOCOMO_KIC);
^1da177e4c3f415 Linus Torvalds    2005-04-16  402  
^1da177e4c3f415 Linus Torvalds    2005-04-16  403  	/* GPIO */
^1da177e4c3f415 Linus Torvalds    2005-04-16  404  	locomo_writel(0, lchip->base + LOCOMO_GPO);
2a52efb2cecf782 Thomas Kunze      2008-04-29  405  	locomo_writel((LOCOMO_GPIO(1) | LOCOMO_GPIO(2) | LOCOMO_GPIO(13) | LOCOMO_GPIO(14))
^1da177e4c3f415 Linus Torvalds    2005-04-16  406  			, lchip->base + LOCOMO_GPE);
2a52efb2cecf782 Thomas Kunze      2008-04-29  407  	locomo_writel((LOCOMO_GPIO(1) | LOCOMO_GPIO(2) | LOCOMO_GPIO(13) | LOCOMO_GPIO(14))
^1da177e4c3f415 Linus Torvalds    2005-04-16  408  			, lchip->base + LOCOMO_GPD);
^1da177e4c3f415 Linus Torvalds    2005-04-16  409  	locomo_writel(0, lchip->base + LOCOMO_GIE);
^1da177e4c3f415 Linus Torvalds    2005-04-16  410  
e44237818500257 Richard Purdie    2006-06-26  411  	/* Frontlight */
^1da177e4c3f415 Linus Torvalds    2005-04-16  412  	locomo_writel(0, lchip->base + LOCOMO_FRONTLIGHT + LOCOMO_ALS);
^1da177e4c3f415 Linus Torvalds    2005-04-16  413  	locomo_writel(0, lchip->base + LOCOMO_FRONTLIGHT + LOCOMO_ALD);
4ebf2d00260bac5 Pavel Machek      2006-03-15  414  
^1da177e4c3f415 Linus Torvalds    2005-04-16  415  	/* Longtime timer */
^1da177e4c3f415 Linus Torvalds    2005-04-16  416  	locomo_writel(0, lchip->base + LOCOMO_LTINT);
^1da177e4c3f415 Linus Torvalds    2005-04-16  417  	/* SPI */
1b0d76cb9d5a655 H Hartley Sweeten 2010-03-22  418  	locomo_writel(0, lchip->base + LOCOMO_SPI + LOCOMO_SPIIE);
^1da177e4c3f415 Linus Torvalds    2005-04-16  419  
^1da177e4c3f415 Linus Torvalds    2005-04-16  420  	locomo_writel(6 + 8 + 320 + 30 - 10, lchip->base + LOCOMO_ASD);
^1da177e4c3f415 Linus Torvalds    2005-04-16  421  	r = locomo_readl(lchip->base + LOCOMO_ASD);
^1da177e4c3f415 Linus Torvalds    2005-04-16  422  	r |= 0x8000;
^1da177e4c3f415 Linus Torvalds    2005-04-16  423  	locomo_writel(r, lchip->base + LOCOMO_ASD);
^1da177e4c3f415 Linus Torvalds    2005-04-16  424  
^1da177e4c3f415 Linus Torvalds    2005-04-16  425  	locomo_writel(6 + 8 + 320 + 30 - 10 - 128 + 4, lchip->base + LOCOMO_HSD);
^1da177e4c3f415 Linus Torvalds    2005-04-16  426  	r = locomo_readl(lchip->base + LOCOMO_HSD);
^1da177e4c3f415 Linus Torvalds    2005-04-16  427  	r |= 0x8000;
^1da177e4c3f415 Linus Torvalds    2005-04-16  428  	locomo_writel(r, lchip->base + LOCOMO_HSD);
^1da177e4c3f415 Linus Torvalds    2005-04-16  429  
^1da177e4c3f415 Linus Torvalds    2005-04-16  430  	locomo_writel(128 / 8, lchip->base + LOCOMO_HSC);
^1da177e4c3f415 Linus Torvalds    2005-04-16  431  
^1da177e4c3f415 Linus Torvalds    2005-04-16  432  	/* XON */
^1da177e4c3f415 Linus Torvalds    2005-04-16  433  	locomo_writel(0x80, lchip->base + LOCOMO_TADC);
^1da177e4c3f415 Linus Torvalds    2005-04-16  434  	udelay(1000);
^1da177e4c3f415 Linus Torvalds    2005-04-16  435  	/* CLK9MEN */
^1da177e4c3f415 Linus Torvalds    2005-04-16  436  	r = locomo_readl(lchip->base + LOCOMO_TADC);
^1da177e4c3f415 Linus Torvalds    2005-04-16  437  	r |= 0x10;
^1da177e4c3f415 Linus Torvalds    2005-04-16  438  	locomo_writel(r, lchip->base + LOCOMO_TADC);
^1da177e4c3f415 Linus Torvalds    2005-04-16  439  	udelay(100);
^1da177e4c3f415 Linus Torvalds    2005-04-16  440  
^1da177e4c3f415 Linus Torvalds    2005-04-16  441  	/* init DAC */
^1da177e4c3f415 Linus Torvalds    2005-04-16  442  	r = locomo_readl(lchip->base + LOCOMO_DAC);
^1da177e4c3f415 Linus Torvalds    2005-04-16  443  	r |= LOCOMO_DAC_SCLOEB | LOCOMO_DAC_SDAOEB;
^1da177e4c3f415 Linus Torvalds    2005-04-16  444  	locomo_writel(r, lchip->base + LOCOMO_DAC);
^1da177e4c3f415 Linus Torvalds    2005-04-16  445  
^1da177e4c3f415 Linus Torvalds    2005-04-16  446  	r = locomo_readl(lchip->base + LOCOMO_VER);
^1da177e4c3f415 Linus Torvalds    2005-04-16  447  	printk(KERN_INFO "LoCoMo Chip: %lu%lu\n", (r >> 8), (r & 0xff));
^1da177e4c3f415 Linus Torvalds    2005-04-16  448  
^1da177e4c3f415 Linus Torvalds    2005-04-16  449  	/*
^1da177e4c3f415 Linus Torvalds    2005-04-16  450  	 * The interrupt controller must be initialised before any
^1da177e4c3f415 Linus Torvalds    2005-04-16  451  	 * other device to ensure that the interrupts are available.
^1da177e4c3f415 Linus Torvalds    2005-04-16  452  	 */
ac609d266e4af4e Eric Miao         2010-02-04  453  	if (lchip->irq != NO_IRQ && lchip->irq_base != NO_IRQ)
^1da177e4c3f415 Linus Torvalds    2005-04-16  454  		locomo_setup_irq(lchip);
^1da177e4c3f415 Linus Torvalds    2005-04-16  455  
^1da177e4c3f415 Linus Torvalds    2005-04-16  456  	for (i = 0; i < ARRAY_SIZE(locomo_devices); i++)
^1da177e4c3f415 Linus Torvalds    2005-04-16  457  		locomo_init_one_child(lchip, &locomo_devices[i]);
^1da177e4c3f415 Linus Torvalds    2005-04-16  458  	return 0;
^1da177e4c3f415 Linus Torvalds    2005-04-16  459  
^1da177e4c3f415 Linus Torvalds    2005-04-16  460   out:
^1da177e4c3f415 Linus Torvalds    2005-04-16  461  	kfree(lchip);
^1da177e4c3f415 Linus Torvalds    2005-04-16  462  	return ret;
^1da177e4c3f415 Linus Torvalds    2005-04-16  463  }
^1da177e4c3f415 Linus Torvalds    2005-04-16  464  

---
0-DAY CI Kernel Test Service, Intel Corporation
https://lists.01.org/hyperkitty/list/kbuild-all@lists.01.org

[-- Attachment #2: .config.gz --]
[-- Type: application/gzip, Size: 31215 bytes --]

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 27/27] scripts: kernel-doc: validate kernel-doc markup with the actual names
  2020-11-16 10:18 ` [PATCH v4 27/27] scripts: kernel-doc: validate kernel-doc markup with the actual names Mauro Carvalho Chehab
  2020-11-16 15:06   ` kernel test robot
  2020-11-16 15:42   ` kernel test robot
@ 2020-11-16 15:51   ` kernel test robot
  2 siblings, 0 replies; 51+ messages in thread
From: kernel test robot @ 2020-11-16 15:51 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Jonathan Corbet
  Cc: kbuild-all, clang-built-linux, linux-media,
	Mauro Carvalho Chehab, Linux Doc Mailing List, linux-kernel

[-- Attachment #1: Type: text/plain, Size: 11571 bytes --]

Hi Mauro,

I love your patch! Perhaps something to improve:

[auto build test WARNING on next-20201116]
[cannot apply to drm-intel/for-linux-next s390/features tip/timers/core tip/irq/core tip/sched/core linus/master hnaz-linux-mm/master v5.10-rc4 v5.10-rc3 v5.10-rc2 v5.10-rc4]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch]

url:    https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/net-phy-fix-kernel-doc-markups/20201116-191847
base:    034307507118f7e1b18f8403c85af2216da2dc94
config: x86_64-randconfig-r024-20201116 (attached as .config)
compiler: clang version 12.0.0 (https://github.com/llvm/llvm-project c044709b8fbea2a9a375e4173a6bd735f6866c0c)
reproduce (this is a W=1 build):
        wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
        chmod +x ~/bin/make.cross
        # install x86_64 cross compiling tool for clang build
        # apt-get install binutils-x86-64-linux-gnu
        # https://github.com/0day-ci/linux/commit/11cd9cdaab434fff7a5edbee8d8d4ce9ef11acf4
        git remote add linux-review https://github.com/0day-ci/linux
        git fetch --no-tags linux-review Mauro-Carvalho-Chehab/net-phy-fix-kernel-doc-markups/20201116-191847
        git checkout 11cd9cdaab434fff7a5edbee8d8d4ce9ef11acf4
        # save the attached .config to linux build tree
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=clang make.cross ARCH=x86_64 

If you fix the issue, kindly add following tag as appropriate
Reported-by: kernel test robot <lkp@intel.com>

All warnings (new ones prefixed by >>):

>> drivers/staging/gasket/gasket_core.c:1556: warning: wrong kernel-doc identifier on line:
    * Lookup a name by number in a num_name table.
   drivers/staging/gasket/gasket_core.c:1655: warning: wrong kernel-doc identifier on line:
    * Asynchronously waits on device.
--
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:46: warning: Enum value 'LOADER_CMD_XFER_QUERY' not described in enum 'ish_loader_commands'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:46: warning: Enum value 'LOADER_CMD_XFER_FRAGMENT' not described in enum 'ish_loader_commands'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:46: warning: Enum value 'LOADER_CMD_START' not described in enum 'ish_loader_commands'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:108: warning: Function parameter or member 'reserved' not described in 'loader_msg_hdr'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:196: warning: Function parameter or member 'data' not described in 'response_info'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:196: warning: Function parameter or member 'max_size' not described in 'response_info'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:196: warning: Function parameter or member 'size' not described in 'response_info'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:196: warning: Function parameter or member 'error' not described in 'response_info'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:196: warning: Function parameter or member 'received' not described in 'response_info'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:196: warning: Function parameter or member 'wait_queue' not described in 'response_info'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:233: warning: Function parameter or member 'loader_ishtp_cl' not described in 'ishtp_cl_data'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:233: warning: Function parameter or member 'cl_device' not described in 'ishtp_cl_data'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:233: warning: Function parameter or member 'response' not described in 'ishtp_cl_data'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:233: warning: Function parameter or member 'flag_retry' not described in 'ishtp_cl_data'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:233: warning: Function parameter or member 'retry_count' not described in 'ishtp_cl_data'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:252: warning: Function parameter or member 'client_data' not described in 'get_firmware_variant'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:252: warning: Function parameter or member 'filename' not described in 'get_firmware_variant'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:281: warning: Function parameter or member 'out_msg' not described in 'loader_cl_send'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:281: warning: Function parameter or member 'out_size' not described in 'loader_cl_send'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:281: warning: Function parameter or member 'in_msg' not described in 'loader_cl_send'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:281: warning: Function parameter or member 'in_size' not described in 'loader_cl_send'
>> drivers/hid/intel-ish-hid/ishtp-fw-loader.c:281: warning: expecting prototype for Send message from host to firmware(). Prototype was for loader_cl_send() instead
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:445: warning: Function parameter or member 'cl_device' not described in 'loader_cl_event_cb'
   drivers/hid/intel-ish-hid/ishtp-fw-loader.c:445: warning: Excess function parameter 'device' description in 'loader_cl_event_cb'
>> drivers/hid/intel-ish-hid/ishtp-fw-loader.c:551: warning: expecting prototype for Loads ISH firmware using ishtp interface(). Prototype was for ish_fw_xfer_ishtp() instead
>> drivers/hid/intel-ish-hid/ishtp-fw-loader.c:745: warning: expecting prototype for Start executing ISH main firmware(). Prototype was for ish_fw_start() instead
>> drivers/hid/intel-ish-hid/ishtp-fw-loader.c:767: warning: expecting prototype for Loads ISH firmware from host(). Prototype was for load_fw_from_host() instead
--
>> drivers/gpu/drm/gma500/intel_gmbus.c:386: warning: expecting prototype for intel_gmbus_setup(). Prototype was for gma_intel_setup_gmbus() instead
--
   drivers/gpu/drm/gma500/intel_bios.c:581: warning: Function parameter or member 'dev' not described in 'psb_intel_destroy_bios'
>> drivers/gpu/drm/gma500/intel_bios.c:581: warning: expecting prototype for Destroy and free VBT data(). Prototype was for psb_intel_destroy_bios() instead
--
   drivers/gpu/drm/gma500/gma_display.c:27: warning: Function parameter or member 'crtc' not described in 'gma_pipe_has_type'
   drivers/gpu/drm/gma500/gma_display.c:27: warning: Function parameter or member 'type' not described in 'gma_pipe_has_type'
>> drivers/gpu/drm/gma500/gma_display.c:27: warning: expecting prototype for Returns whether any output on the specified pipe is of the specified type(). Prototype was for gma_pipe_has_type() instead
>> drivers/gpu/drm/gma500/gma_display.c:184: warning: wrong kernel-doc identifier on line:
    * Sets the power management mode of the pipe and plane.
   drivers/gpu/drm/gma500/gma_display.c:573: warning: Function parameter or member 'crtc' not described in 'gma_crtc_save'
>> drivers/gpu/drm/gma500/gma_display.c:573: warning: expecting prototype for Save HW states of given crtc(). Prototype was for gma_crtc_save() instead
   drivers/gpu/drm/gma500/gma_display.c:616: warning: Function parameter or member 'crtc' not described in 'gma_crtc_restore'
>> drivers/gpu/drm/gma500/gma_display.c:616: warning: expecting prototype for Restore HW states of given crtc(). Prototype was for gma_crtc_restore() instead
--
>> drivers/gpu/drm/gma500/psb_irq.c:130: warning: wrong kernel-doc identifier on line:
    * Display controller interrupt handler for pipe event.
--
>> drivers/gpu/drm/gma500/psb_intel_display.c:75: warning: wrong kernel-doc identifier on line:
    * Return the pipe currently connected to the panel fitter,
--
   drivers/gpu/drm/gma500/psb_intel_sdvo.c:230: warning: Function parameter or member 'psb_intel_sdvo' not described in 'psb_intel_sdvo_write_sdvox'
   drivers/gpu/drm/gma500/psb_intel_sdvo.c:230: warning: Function parameter or member 'val' not described in 'psb_intel_sdvo_write_sdvox'
>> drivers/gpu/drm/gma500/psb_intel_sdvo.c:230: warning: expecting prototype for but always writes both(). Prototype was for psb_intel_sdvo_write_sdvox() instead
>> drivers/gpu/drm/gma500/psb_intel_sdvo.c:592: warning: wrong kernel-doc identifier on line:
    * Return whether each input is trained.
   drivers/gpu/drm/gma500/psb_intel_sdvo.c:1831: warning: Function parameter or member 'dev_priv' not described in 'psb_intel_sdvo_select_ddc_bus'
   drivers/gpu/drm/gma500/psb_intel_sdvo.c:1831: warning: Function parameter or member 'sdvo' not described in 'psb_intel_sdvo_select_ddc_bus'
   drivers/gpu/drm/gma500/psb_intel_sdvo.c:1831: warning: Function parameter or member 'reg' not described in 'psb_intel_sdvo_select_ddc_bus'
>> drivers/gpu/drm/gma500/psb_intel_sdvo.c:1831: warning: expecting prototype for Choose the appropriate DDC bus for control bus switch command for this(). Prototype was for psb_intel_sdvo_select_ddc_bus() instead
--
   drivers/gpu/drm/mga/mga_ioc32.c:2: warning: Cannot understand  * \file mga_ioc32.c
    on line 2 - I thought it was a doc line
   drivers/gpu/drm/mga/mga_ioc32.c:171: warning: Function parameter or member 'filp' not described in 'mga_compat_ioctl'
   drivers/gpu/drm/mga/mga_ioc32.c:171: warning: Function parameter or member 'cmd' not described in 'mga_compat_ioctl'
   drivers/gpu/drm/mga/mga_ioc32.c:171: warning: Function parameter or member 'arg' not described in 'mga_compat_ioctl'
>> drivers/gpu/drm/mga/mga_ioc32.c:171: warning: expecting prototype for Called whenever a 32(). Prototype was for mga_compat_ioctl() instead

vim +1556 drivers/staging/gasket/gasket_core.c

80666096eb78f0e Todd Poynor 2018-07-31  1554  
80666096eb78f0e Todd Poynor 2018-07-31  1555  /**
80666096eb78f0e Todd Poynor 2018-07-31 @1556   * Lookup a name by number in a num_name table.
80666096eb78f0e Todd Poynor 2018-07-31  1557   * @num: Number to lookup.
80666096eb78f0e Todd Poynor 2018-07-31  1558   * @table: Array of num_name structures, the table for the lookup.
80666096eb78f0e Todd Poynor 2018-07-31  1559   *
80666096eb78f0e Todd Poynor 2018-07-31  1560   * Description: Searches for num in the table.  If found, the
80666096eb78f0e Todd Poynor 2018-07-31  1561   *		corresponding name is returned; otherwise NULL
80666096eb78f0e Todd Poynor 2018-07-31  1562   *		is returned.
80666096eb78f0e Todd Poynor 2018-07-31  1563   *
80666096eb78f0e Todd Poynor 2018-07-31  1564   *		The table must have a NULL name pointer at the end.
80666096eb78f0e Todd Poynor 2018-07-31  1565   */
88c8a377c00ff3a Todd Poynor 2018-07-31  1566  const char *gasket_num_name_lookup(uint num,
88c8a377c00ff3a Todd Poynor 2018-07-31  1567  				   const struct gasket_num_name *table)
80666096eb78f0e Todd Poynor 2018-07-31  1568  {
80666096eb78f0e Todd Poynor 2018-07-31  1569  	uint i = 0;
80666096eb78f0e Todd Poynor 2018-07-31  1570  
80666096eb78f0e Todd Poynor 2018-07-31  1571  	while (table[i].snn_name) {
80666096eb78f0e Todd Poynor 2018-07-31  1572  		if (num == table[i].snn_num)
9a69f5087ccc20b Simon Que   2018-06-29  1573  			break;
80666096eb78f0e Todd Poynor 2018-07-31  1574  		++i;
9a69f5087ccc20b Simon Que   2018-06-29  1575  	}
9a69f5087ccc20b Simon Que   2018-06-29  1576  
80666096eb78f0e Todd Poynor 2018-07-31  1577  	return table[i].snn_name;
80666096eb78f0e Todd Poynor 2018-07-31  1578  }
80666096eb78f0e Todd Poynor 2018-07-31  1579  EXPORT_SYMBOL(gasket_num_name_lookup);
80666096eb78f0e Todd Poynor 2018-07-31  1580  

---
0-DAY CI Kernel Test Service, Intel Corporation
https://lists.01.org/hyperkitty/list/kbuild-all@lists.01.org

[-- Attachment #2: .config.gz --]
[-- Type: application/gzip, Size: 32328 bytes --]

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 10/27] video: fix some kernel-doc markups
  2020-11-16 15:36   ` Daniel Vetter
@ 2020-11-16 16:38     ` Mauro Carvalho Chehab
  2020-11-16 17:24       ` Daniel Vetter
  0 siblings, 1 reply; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 16:38 UTC (permalink / raw)
  To: Daniel Vetter
  Cc: Linux Doc Mailing List, Jonathan Corbet,
	Bartlomiej Zolnierkiewicz, Bernard Zhao, Boris Brezillon,
	Daniel Vetter, Gwan-gyeong Mun, Laurent Pinchart, Sam Ravnborg,
	Sebastian Reichel, Thomas Zimmermann, dri-devel, linux-fbdev,
	linux-kernel

Em Mon, 16 Nov 2020 16:36:06 +0100
Daniel Vetter <daniel@ffwll.ch> escreveu:

> On Mon, Nov 16, 2020 at 11:18:06AM +0100, 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>  
> 
> Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> 
> I'm assuming you're sending a pull request for this.

Feel free to just merge it via your tree. Patches here are pretty
much independent ;-)

> -Daniel
> 
> > ---
> >  drivers/video/fbdev/core/fbcmap.c | 2 +-
> >  drivers/video/hdmi.c              | 3 ++-
> >  2 files changed, 3 insertions(+), 2 deletions(-)
> > 
> > diff --git a/drivers/video/fbdev/core/fbcmap.c b/drivers/video/fbdev/core/fbcmap.c
> > index e5ae33c1a8e8..757d5c3f620b 100644
> > --- a/drivers/video/fbdev/core/fbcmap.c
> > +++ b/drivers/video/fbdev/core/fbcmap.c
> > @@ -59,41 +59,41 @@ static u16 blue16[] __read_mostly = {
> >      0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa,
> >      0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff
> >  };
> >  
> >  static const struct fb_cmap default_2_colors = {
> >      .len=2, .red=red2, .green=green2, .blue=blue2
> >  };
> >  static const struct fb_cmap default_8_colors = {
> >      .len=8, .red=red8, .green=green8, .blue=blue8
> >  };
> >  static const struct fb_cmap default_4_colors = {
> >      .len=4, .red=red4, .green=green4, .blue=blue4
> >  };
> >  static const struct fb_cmap default_16_colors = {
> >      .len=16, .red=red16, .green=green16, .blue=blue16
> >  };
> >  
> >  
> >  
> >  /**
> > - *	fb_alloc_cmap - allocate a colormap
> > + *	fb_alloc_cmap_gfp - allocate a colormap
> >   *	@cmap: frame buffer colormap structure
> >   *	@len: length of @cmap
> >   *	@transp: boolean, 1 if there is transparency, 0 otherwise
> >   *	@flags: flags for kmalloc memory allocation
> >   *
> >   *	Allocates memory for a colormap @cmap.  @len is the
> >   *	number of entries in the palette.
> >   *
> >   *	Returns negative errno on error, or zero on success.
> >   *
> >   */
> >  
> >  int fb_alloc_cmap_gfp(struct fb_cmap *cmap, int len, int transp, gfp_t flags)
> >  {
> >  	int size = len * sizeof(u16);
> >  	int ret = -ENOMEM;
> >  
> >  	flags |= __GFP_NOWARN;
> >  
> >  	if (cmap->len != len) {
> > diff --git a/drivers/video/hdmi.c b/drivers/video/hdmi.c
> > index 1e4cb63d0d11..947be761dfa4 100644
> > --- a/drivers/video/hdmi.c
> > +++ b/drivers/video/hdmi.c
> > @@ -1675,41 +1675,42 @@ static int hdmi_audio_infoframe_unpack(struct hdmi_audio_infoframe *frame,
> >  
> >  	ret = hdmi_audio_infoframe_init(frame);
> >  	if (ret)
> >  		return ret;
> >  
> >  	ptr += HDMI_INFOFRAME_HEADER_SIZE;
> >  
> >  	frame->channels = ptr[0] & 0x7;
> >  	frame->coding_type = (ptr[0] >> 4) & 0xf;
> >  	frame->sample_size = ptr[1] & 0x3;
> >  	frame->sample_frequency = (ptr[1] >> 2) & 0x7;
> >  	frame->coding_type_ext = ptr[2] & 0x1f;
> >  	frame->channel_allocation = ptr[3];
> >  	frame->level_shift_value = (ptr[4] >> 3) & 0xf;
> >  	frame->downmix_inhibit = ptr[4] & 0x80 ? true : false;
> >  
> >  	return 0;
> >  }
> >  
> >  /**
> > - * hdmi_vendor_infoframe_unpack() - unpack binary buffer to a HDMI vendor infoframe
> > + * hdmi_vendor_any_infoframe_unpack() - unpack binary buffer to a HDMI
> > + * 	vendor infoframe
> >   * @frame: HDMI Vendor infoframe
> >   * @buffer: source buffer
> >   * @size: size of buffer
> >   *
> >   * Unpacks the information contained in binary @buffer into a structured
> >   * @frame of the HDMI Vendor information frame.
> >   * Also verifies the checksum as required by section 5.3.5 of the HDMI 1.4
> >   * specification.
> >   *
> >   * Returns 0 on success or a negative error code on failure.
> >   */
> >  static int
> >  hdmi_vendor_any_infoframe_unpack(union hdmi_vendor_any_infoframe *frame,
> >  				 const void *buffer, size_t size)
> >  {
> >  	const u8 *ptr = buffer;
> >  	size_t length;
> >  	int ret;
> >  	u8 hdmi_video_format;
> >  	struct hdmi_vendor_infoframe *hvf = &frame->hdmi;
> > -- 
> > 2.28.0
> >   
> 



Thanks,
Mauro

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 10/27] video: fix some kernel-doc markups
  2020-11-16 16:38     ` Mauro Carvalho Chehab
@ 2020-11-16 17:24       ` Daniel Vetter
  2020-11-16 18:11         ` Sam Ravnborg
  2020-11-16 18:42         ` Mauro Carvalho Chehab
  0 siblings, 2 replies; 51+ messages in thread
From: Daniel Vetter @ 2020-11-16 17:24 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Daniel Vetter, Linux Doc Mailing List, Jonathan Corbet,
	Bartlomiej Zolnierkiewicz, Bernard Zhao, Boris Brezillon,
	Daniel Vetter, Gwan-gyeong Mun, Laurent Pinchart, Sam Ravnborg,
	Sebastian Reichel, Thomas Zimmermann, dri-devel, linux-fbdev,
	linux-kernel

On Mon, Nov 16, 2020 at 05:38:04PM +0100, Mauro Carvalho Chehab wrote:
> Em Mon, 16 Nov 2020 16:36:06 +0100
> Daniel Vetter <daniel@ffwll.ch> escreveu:
> 
> > On Mon, Nov 16, 2020 at 11:18:06AM +0100, 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>  
> > 
> > Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> > 
> > I'm assuming you're sending a pull request for this.
> 
> Feel free to just merge it via your tree. Patches here are pretty
> much independent ;-)

Ok I put it into drm-misc-next. I kinda assumed since there's also a huge
effort going on to shut up warnings, plus I think kerneldoc issues are
reported by a bunch of build bots nowadays. So assumed you pile this all
up.
-Daniel

> 
> > -Daniel
> > 
> > > ---
> > >  drivers/video/fbdev/core/fbcmap.c | 2 +-
> > >  drivers/video/hdmi.c              | 3 ++-
> > >  2 files changed, 3 insertions(+), 2 deletions(-)
> > > 
> > > diff --git a/drivers/video/fbdev/core/fbcmap.c b/drivers/video/fbdev/core/fbcmap.c
> > > index e5ae33c1a8e8..757d5c3f620b 100644
> > > --- a/drivers/video/fbdev/core/fbcmap.c
> > > +++ b/drivers/video/fbdev/core/fbcmap.c
> > > @@ -59,41 +59,41 @@ static u16 blue16[] __read_mostly = {
> > >      0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa, 0x0000, 0xaaaa,
> > >      0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff, 0x5555, 0xffff
> > >  };
> > >  
> > >  static const struct fb_cmap default_2_colors = {
> > >      .len=2, .red=red2, .green=green2, .blue=blue2
> > >  };
> > >  static const struct fb_cmap default_8_colors = {
> > >      .len=8, .red=red8, .green=green8, .blue=blue8
> > >  };
> > >  static const struct fb_cmap default_4_colors = {
> > >      .len=4, .red=red4, .green=green4, .blue=blue4
> > >  };
> > >  static const struct fb_cmap default_16_colors = {
> > >      .len=16, .red=red16, .green=green16, .blue=blue16
> > >  };
> > >  
> > >  
> > >  
> > >  /**
> > > - *	fb_alloc_cmap - allocate a colormap
> > > + *	fb_alloc_cmap_gfp - allocate a colormap
> > >   *	@cmap: frame buffer colormap structure
> > >   *	@len: length of @cmap
> > >   *	@transp: boolean, 1 if there is transparency, 0 otherwise
> > >   *	@flags: flags for kmalloc memory allocation
> > >   *
> > >   *	Allocates memory for a colormap @cmap.  @len is the
> > >   *	number of entries in the palette.
> > >   *
> > >   *	Returns negative errno on error, or zero on success.
> > >   *
> > >   */
> > >  
> > >  int fb_alloc_cmap_gfp(struct fb_cmap *cmap, int len, int transp, gfp_t flags)
> > >  {
> > >  	int size = len * sizeof(u16);
> > >  	int ret = -ENOMEM;
> > >  
> > >  	flags |= __GFP_NOWARN;
> > >  
> > >  	if (cmap->len != len) {
> > > diff --git a/drivers/video/hdmi.c b/drivers/video/hdmi.c
> > > index 1e4cb63d0d11..947be761dfa4 100644
> > > --- a/drivers/video/hdmi.c
> > > +++ b/drivers/video/hdmi.c
> > > @@ -1675,41 +1675,42 @@ static int hdmi_audio_infoframe_unpack(struct hdmi_audio_infoframe *frame,
> > >  
> > >  	ret = hdmi_audio_infoframe_init(frame);
> > >  	if (ret)
> > >  		return ret;
> > >  
> > >  	ptr += HDMI_INFOFRAME_HEADER_SIZE;
> > >  
> > >  	frame->channels = ptr[0] & 0x7;
> > >  	frame->coding_type = (ptr[0] >> 4) & 0xf;
> > >  	frame->sample_size = ptr[1] & 0x3;
> > >  	frame->sample_frequency = (ptr[1] >> 2) & 0x7;
> > >  	frame->coding_type_ext = ptr[2] & 0x1f;
> > >  	frame->channel_allocation = ptr[3];
> > >  	frame->level_shift_value = (ptr[4] >> 3) & 0xf;
> > >  	frame->downmix_inhibit = ptr[4] & 0x80 ? true : false;
> > >  
> > >  	return 0;
> > >  }
> > >  
> > >  /**
> > > - * hdmi_vendor_infoframe_unpack() - unpack binary buffer to a HDMI vendor infoframe
> > > + * hdmi_vendor_any_infoframe_unpack() - unpack binary buffer to a HDMI
> > > + * 	vendor infoframe
> > >   * @frame: HDMI Vendor infoframe
> > >   * @buffer: source buffer
> > >   * @size: size of buffer
> > >   *
> > >   * Unpacks the information contained in binary @buffer into a structured
> > >   * @frame of the HDMI Vendor information frame.
> > >   * Also verifies the checksum as required by section 5.3.5 of the HDMI 1.4
> > >   * specification.
> > >   *
> > >   * Returns 0 on success or a negative error code on failure.
> > >   */
> > >  static int
> > >  hdmi_vendor_any_infoframe_unpack(union hdmi_vendor_any_infoframe *frame,
> > >  				 const void *buffer, size_t size)
> > >  {
> > >  	const u8 *ptr = buffer;
> > >  	size_t length;
> > >  	int ret;
> > >  	u8 hdmi_video_format;
> > >  	struct hdmi_vendor_infoframe *hvf = &frame->hdmi;
> > > -- 
> > > 2.28.0
> > >   
> > 
> 
> 
> 
> Thanks,
> Mauro

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 10/27] video: fix some kernel-doc markups
  2020-11-16 17:24       ` Daniel Vetter
@ 2020-11-16 18:11         ` Sam Ravnborg
  2020-11-16 19:43           ` Daniel Vetter
  2020-11-16 18:42         ` Mauro Carvalho Chehab
  1 sibling, 1 reply; 51+ messages in thread
From: Sam Ravnborg @ 2020-11-16 18:11 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet,
	Bartlomiej Zolnierkiewicz, Bernard Zhao, Boris Brezillon,
	Gwan-gyeong Mun, Laurent Pinchart, Sebastian Reichel,
	Thomas Zimmermann, dri-devel, linux-fbdev, linux-kernel

Hi Daniel
> > Feel free to just merge it via your tree. Patches here are pretty
> > much independent ;-)
> 
> Ok I put it into drm-misc-next. I kinda assumed since there's also a huge
> effort going on to shut up warnings, plus I think kerneldoc issues are
> reported by a bunch of build bots nowadays. So assumed you pile this all
> up.

Any reason "drm: fix some kernel-doc markups" was not applied?

	Sam

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 10/27] video: fix some kernel-doc markups
  2020-11-16 17:24       ` Daniel Vetter
  2020-11-16 18:11         ` Sam Ravnborg
@ 2020-11-16 18:42         ` Mauro Carvalho Chehab
  1 sibling, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-16 18:42 UTC (permalink / raw)
  To: Daniel Vetter
  Cc: Linux Doc Mailing List, Jonathan Corbet,
	Bartlomiej Zolnierkiewicz, Bernard Zhao, Boris Brezillon,
	Daniel Vetter, Gwan-gyeong Mun, Laurent Pinchart, Sam Ravnborg,
	Sebastian Reichel, Thomas Zimmermann, dri-devel, linux-fbdev,
	linux-kernel

Em Mon, 16 Nov 2020 18:24:04 +0100
Daniel Vetter <daniel@ffwll.ch> escreveu:

> On Mon, Nov 16, 2020 at 05:38:04PM +0100, Mauro Carvalho Chehab wrote:
> > Em Mon, 16 Nov 2020 16:36:06 +0100
> > Daniel Vetter <daniel@ffwll.ch> escreveu:
> >   
> > > On Mon, Nov 16, 2020 at 11:18:06AM +0100, 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>    
> > > 
> > > Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
> > > 
> > > I'm assuming you're sending a pull request for this.  
> > 
> > Feel free to just merge it via your tree. Patches here are pretty
> > much independent ;-)  
> 
> Ok I put it into drm-misc-next. I kinda assumed since there's also a huge
> effort going on to shut up warnings, plus I think kerneldoc issues are
> reported by a bunch of build bots nowadays. So assumed you pile this all
> up.

Currently, this doesn't generate any warnings (which, IMHO, it is a
very bad thing). The final patch on this series actually such warning. 
My plan is to have the final patch merged for Kernel 5.11.

So, at least from PoV of shut up warnings[1], this patch be either
be merged for 5.11 or earlier.

Regards,
Mauro

-

[1] Basically, if you do:

	/**
	 * foo - some foo func
	 */
	int bar(...)

the documentation will be for "bar()" function, instead of
"foo()", as Kernel-doc currently simply ignores "foo".

On several places, this is due to a typo or a function
rename, but there are a few places where a "bar()" function
got added between the kernel-doc markup and "foo()" function,
thus producing wrong docs. Don't remember if are there any
such issues under drivers/video or drivers/gpu.

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 10/27] video: fix some kernel-doc markups
  2020-11-16 18:11         ` Sam Ravnborg
@ 2020-11-16 19:43           ` Daniel Vetter
  0 siblings, 0 replies; 51+ messages in thread
From: Daniel Vetter @ 2020-11-16 19:43 UTC (permalink / raw)
  To: Sam Ravnborg
  Cc: Mauro Carvalho Chehab, Linux Doc Mailing List, Jonathan Corbet,
	Bartlomiej Zolnierkiewicz, Bernard Zhao, Boris Brezillon,
	Gwan-gyeong Mun, Laurent Pinchart, Sebastian Reichel,
	Thomas Zimmermann, dri-devel, linux-fbdev, linux-kernel

On Mon, Nov 16, 2020 at 07:11:12PM +0100, Sam Ravnborg wrote:
> Hi Daniel
> > > Feel free to just merge it via your tree. Patches here are pretty
> > > much independent ;-)
> > 
> > Ok I put it into drm-misc-next. I kinda assumed since there's also a huge
> > effort going on to shut up warnings, plus I think kerneldoc issues are
> > reported by a bunch of build bots nowadays. So assumed you pile this all
> > up.
> 
> Any reason "drm: fix some kernel-doc markups" was not applied?

Oh somehow I thought that one was only for i915 issues. I guess I'll take
a look.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 05/27] drm: fix some kernel-doc markups
  2020-11-16 11:37   ` Jani Nikula
@ 2020-11-16 19:48     ` Daniel Vetter
  0 siblings, 0 replies; 51+ messages in thread
From: Daniel Vetter @ 2020-11-16 19:48 UTC (permalink / raw)
  To: Jani Nikula
  Cc: Mauro Carvalho Chehab, Daniel Vetter, David Airlie,
	Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann,
	Christian König, Jonathan Corbet,
	José Roberto de Souza, Linux Doc Mailing List,
	Ville Syrjälä,
	Alex Deucher, Andrey Grodzovsky, Eric Anholt, Imre Deak,
	Joonas Lahtinen, Luben Tuikov, Lucas Stach, Matt Roper,
	Nirmoy Das, Pankaj Bharadiya, Rodrigo Vivi, Tejas Upadhyay,
	Wambui Karuga, Yintian Tao, changzhu, dri-devel, intel-gfx,
	linux-kernel

On Mon, Nov 16, 2020 at 01:37:11PM +0200, Jani Nikula wrote:
> On Mon, 16 Nov 2020, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> > Some identifiers have different names between their prototypes
> > and the kernel-doc markup.
> >
> > Others need to be fixed, as kernel-doc markups should use this format:
> >         identifier - description
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  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 +++++---
> 
> For the i915 parts,
> 
> Acked-by: Jani Nikula <jani.nikula@intel.com>
> 
> for merging via whichever tree.

Smashed into drm-misc-next.
-Daniel

> 
> >  drivers/gpu/drm/scheduler/sched_main.c        | 2 +-
> >  drivers/gpu/drm/v3d/v3d_sched.c               | 2 +-
> >  drivers/gpu/drm/vc4/vc4_bo.c                  | 2 +-
> >  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 ++++----
> >  20 files changed, 32 insertions(+), 28 deletions(-)
> >
> > diff --git a/drivers/gpu/drm/drm_atomic_state_helper.c b/drivers/gpu/drm/drm_atomic_state_helper.c
> > index 9ad74045158e..ddcf5c2c8e6a 100644
> > --- a/drivers/gpu/drm/drm_atomic_state_helper.c
> > +++ b/drivers/gpu/drm/drm_atomic_state_helper.c
> > @@ -526,41 +526,41 @@ __drm_atomic_helper_connector_destroy_state(struct drm_connector_state *state)
> >  }
> >  EXPORT_SYMBOL(__drm_atomic_helper_connector_destroy_state);
> >  
> >  /**
> >   * drm_atomic_helper_connector_destroy_state - default state destroy hook
> >   * @connector: drm connector
> >   * @state: connector state object to release
> >   *
> >   * Default connector state destroy hook for drivers which don't have their own
> >   * subclassed connector state structure.
> >   */
> >  void drm_atomic_helper_connector_destroy_state(struct drm_connector *connector,
> >  					  struct drm_connector_state *state)
> >  {
> >  	__drm_atomic_helper_connector_destroy_state(state);
> >  	kfree(state);
> >  }
> >  EXPORT_SYMBOL(drm_atomic_helper_connector_destroy_state);
> >  
> >  /**
> > - * __drm_atomic_helper_private_duplicate_state - copy atomic private state
> > + * __drm_atomic_helper_private_obj_duplicate_state - copy atomic private state
> >   * @obj: CRTC object
> >   * @state: new private object state
> >   *
> >   * Copies atomic state from a private objects's current state and resets inferred values.
> >   * This is useful for drivers that subclass the private state.
> >   */
> >  void __drm_atomic_helper_private_obj_duplicate_state(struct drm_private_obj *obj,
> >  						     struct drm_private_state *state)
> >  {
> >  	memcpy(state, obj->state, sizeof(*state));
> >  }
> >  EXPORT_SYMBOL(__drm_atomic_helper_private_obj_duplicate_state);
> >  
> >  /**
> >   * __drm_atomic_helper_bridge_duplicate_state() - Copy atomic bridge state
> >   * @bridge: bridge object
> >   * @state: atomic bridge state
> >   *
> >   * Copies atomic state from a bridge's current state and resets inferred values.
> >   * This is useful for drivers that subclass the bridge state.
> > diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
> > index 1913d8b4e16a..98b6ec45ef96 100644
> > --- a/drivers/gpu/drm/drm_connector.c
> > +++ b/drivers/gpu/drm/drm_connector.c
> > @@ -1415,41 +1415,42 @@ void drm_hdmi_avi_infoframe_content_type(struct hdmi_avi_infoframe *frame,
> >  		break;
> >  	case DRM_MODE_CONTENT_TYPE_CINEMA:
> >  		frame->content_type = HDMI_CONTENT_TYPE_CINEMA;
> >  		break;
> >  	case DRM_MODE_CONTENT_TYPE_GAME:
> >  		frame->content_type = HDMI_CONTENT_TYPE_GAME;
> >  		break;
> >  	case DRM_MODE_CONTENT_TYPE_PHOTO:
> >  		frame->content_type = HDMI_CONTENT_TYPE_PHOTO;
> >  		break;
> >  	default:
> >  		/* Graphics is the default(0) */
> >  		frame->content_type = HDMI_CONTENT_TYPE_GRAPHICS;
> >  	}
> >  
> >  	frame->itc = conn_state->content_type != DRM_MODE_CONTENT_TYPE_NO_DATA;
> >  }
> >  EXPORT_SYMBOL(drm_hdmi_avi_infoframe_content_type);
> >  
> >  /**
> > - * drm_mode_attach_tv_margin_properties - attach TV connector margin properties
> > + * drm_connector_attach_tv_margin_properties - attach TV connector margin
> > + * 	properties
> >   * @connector: DRM connector
> >   *
> >   * Called by a driver when it needs to attach TV margin props to a connector.
> >   * Typically used on SDTV and HDMI connectors.
> >   */
> >  void drm_connector_attach_tv_margin_properties(struct drm_connector *connector)
> >  {
> >  	struct drm_device *dev = connector->dev;
> >  
> >  	drm_object_attach_property(&connector->base,
> >  				   dev->mode_config.tv_left_margin_property,
> >  				   0);
> >  	drm_object_attach_property(&connector->base,
> >  				   dev->mode_config.tv_right_margin_property,
> >  				   0);
> >  	drm_object_attach_property(&connector->base,
> >  				   dev->mode_config.tv_top_margin_property,
> >  				   0);
> >  	drm_object_attach_property(&connector->base,
> >  				   dev->mode_config.tv_bottom_margin_property,
> > diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
> > index 37ec3b94389c..5bd0934004e3 100644
> > --- a/drivers/gpu/drm/drm_dp_helper.c
> > +++ b/drivers/gpu/drm/drm_dp_helper.c
> > @@ -1144,41 +1144,41 @@ drm_dp_subconnector_type(const u8 dpcd[DP_RECEIVER_CAP_SIZE],
> >  	switch (type) {
> >  	case DP_DS_PORT_TYPE_DP:
> >  	case DP_DS_PORT_TYPE_DP_DUALMODE:
> >  		return DRM_MODE_SUBCONNECTOR_DisplayPort;
> >  	case DP_DS_PORT_TYPE_VGA:
> >  		return DRM_MODE_SUBCONNECTOR_VGA;
> >  	case DP_DS_PORT_TYPE_DVI:
> >  		return DRM_MODE_SUBCONNECTOR_DVID;
> >  	case DP_DS_PORT_TYPE_HDMI:
> >  		return DRM_MODE_SUBCONNECTOR_HDMIA;
> >  	case DP_DS_PORT_TYPE_WIRELESS:
> >  		return DRM_MODE_SUBCONNECTOR_Wireless;
> >  	case DP_DS_PORT_TYPE_NON_EDID:
> >  	default:
> >  		return DRM_MODE_SUBCONNECTOR_Unknown;
> >  	}
> >  }
> >  EXPORT_SYMBOL(drm_dp_subconnector_type);
> >  
> >  /**
> > - * drm_mode_set_dp_subconnector_property - set subconnector for DP connector
> > + * drm_dp_set_subconnector_property - set subconnector for DP connector
> >   * @connector: connector to set property on
> >   * @status: connector status
> >   * @dpcd: DisplayPort configuration data
> >   * @port_cap: port capabilities
> >   *
> >   * Called by a driver on every detect event.
> >   */
> >  void drm_dp_set_subconnector_property(struct drm_connector *connector,
> >  				      enum drm_connector_status status,
> >  				      const u8 *dpcd,
> >  				      const u8 port_cap[4])
> >  {
> >  	enum drm_mode_subconnector subconnector = DRM_MODE_SUBCONNECTOR_Unknown;
> >  
> >  	if (status == connector_status_connected)
> >  		subconnector = drm_dp_subconnector_type(dpcd, port_cap);
> >  	drm_object_property_set_value(&connector->base,
> >  			connector->dev->mode_config.dp_subconnector_property,
> >  			subconnector);
> >  }
> > diff --git a/drivers/gpu/drm/drm_framebuffer.c b/drivers/gpu/drm/drm_framebuffer.c
> > index 2f5b0c2bb0fe..aca62ed51e82 100644
> > --- a/drivers/gpu/drm/drm_framebuffer.c
> > +++ b/drivers/gpu/drm/drm_framebuffer.c
> > @@ -535,41 +535,41 @@ int drm_mode_getfb(struct drm_device *dev,
> >  
> >  	/* GET_FB() is an unprivileged ioctl so we must not return a
> >  	 * buffer-handle to non-master processes! For
> >  	 * backwards-compatibility reasons, we cannot make GET_FB() privileged,
> >  	 * so just return an invalid handle for non-masters.
> >  	 */
> >  	if (!drm_is_current_master(file_priv) && !capable(CAP_SYS_ADMIN)) {
> >  		r->handle = 0;
> >  		ret = 0;
> >  		goto out;
> >  	}
> >  
> >  	ret = fb->funcs->create_handle(fb, file_priv, &r->handle);
> >  
> >  out:
> >  	drm_framebuffer_put(fb);
> >  	return ret;
> >  }
> >  
> >  /**
> > - * drm_mode_getfb2 - get extended FB info
> > + * drm_mode_getfb2_ioctl - get extended FB info
> >   * @dev: drm device for the ioctl
> >   * @data: data pointer for the ioctl
> >   * @file_priv: drm file for the ioctl call
> >   *
> >   * Lookup the FB given its ID and return info about it.
> >   *
> >   * Called by the user via ioctl.
> >   *
> >   * Returns:
> >   * Zero on success, negative errno on failure.
> >   */
> >  int drm_mode_getfb2_ioctl(struct drm_device *dev,
> >  			  void *data, struct drm_file *file_priv)
> >  {
> >  	struct drm_mode_fb_cmd2 *r = data;
> >  	struct drm_framebuffer *fb;
> >  	unsigned int i;
> >  	int ret;
> >  
> >  	if (!drm_core_check_feature(dev, DRIVER_MODESET))
> > diff --git a/drivers/gpu/drm/drm_gem.c b/drivers/gpu/drm/drm_gem.c
> > index eb2d23e04be9..92f89cee213e 100644
> > --- a/drivers/gpu/drm/drm_gem.c
> > +++ b/drivers/gpu/drm/drm_gem.c
> > @@ -850,41 +850,41 @@ drm_gem_flink_ioctl(struct drm_device *dev, void *data,
> >  	}
> >  
> >  	if (!obj->name) {
> >  		ret = idr_alloc(&dev->object_name_idr, obj, 1, 0, GFP_KERNEL);
> >  		if (ret < 0)
> >  			goto err;
> >  
> >  		obj->name = ret;
> >  	}
> >  
> >  	args->name = (uint64_t) obj->name;
> >  	ret = 0;
> >  
> >  err:
> >  	mutex_unlock(&dev->object_name_lock);
> >  	drm_gem_object_put(obj);
> >  	return ret;
> >  }
> >  
> >  /**
> > - * drm_gem_open - implementation of the GEM_OPEN ioctl
> > + * drm_gem_open_ioctl - implementation of the GEM_OPEN ioctl
> >   * @dev: drm_device
> >   * @data: ioctl data
> >   * @file_priv: drm file-private structure
> >   *
> >   * Open an object using the global name, returning a handle and the size.
> >   *
> >   * This handle (of course) holds a reference to the object, so the object
> >   * will not go away until the handle is deleted.
> >   */
> >  int
> >  drm_gem_open_ioctl(struct drm_device *dev, void *data,
> >  		   struct drm_file *file_priv)
> >  {
> >  	struct drm_gem_open *args = data;
> >  	struct drm_gem_object *obj;
> >  	int ret;
> >  	u32 handle;
> >  
> >  	if (!drm_core_check_feature(dev, DRIVER_GEM))
> >  		return -EOPNOTSUPP;
> > @@ -895,41 +895,41 @@ drm_gem_open_ioctl(struct drm_device *dev, void *data,
> >  		drm_gem_object_get(obj);
> >  	} else {
> >  		mutex_unlock(&dev->object_name_lock);
> >  		return -ENOENT;
> >  	}
> >  
> >  	/* drm_gem_handle_create_tail unlocks dev->object_name_lock. */
> >  	ret = drm_gem_handle_create_tail(file_priv, obj, &handle);
> >  	if (ret)
> >  		goto err;
> >  
> >  	args->handle = handle;
> >  	args->size = obj->size;
> >  
> >  err:
> >  	drm_gem_object_put(obj);
> >  	return ret;
> >  }
> >  
> >  /**
> > - * gem_gem_open - initalizes GEM file-private structures at devnode open time
> > + * drm_gem_open - initalizes GEM file-private structures at devnode open time
> >   * @dev: drm_device which is being opened by userspace
> >   * @file_private: drm file-private structure to set up
> >   *
> >   * Called at device open time, sets up the structure for handling refcounting
> >   * of mm objects.
> >   */
> >  void
> >  drm_gem_open(struct drm_device *dev, struct drm_file *file_private)
> >  {
> >  	idr_init_base(&file_private->object_idr, 1);
> >  	spin_lock_init(&file_private->table_lock);
> >  }
> >  
> >  /**
> >   * drm_gem_release - release file-private GEM resources
> >   * @dev: drm_device which is being closed by userspace
> >   * @file_private: drm file-private structure to clean up
> >   *
> >   * Called at close time when the filp is going away.
> >   *
> > diff --git a/drivers/gpu/drm/drm_gem_vram_helper.c b/drivers/gpu/drm/drm_gem_vram_helper.c
> > index 889a06696f7e..02ca22e90290 100644
> > --- a/drivers/gpu/drm/drm_gem_vram_helper.c
> > +++ b/drivers/gpu/drm/drm_gem_vram_helper.c
> > @@ -600,41 +600,41 @@ static int drm_gem_vram_bo_driver_move(struct drm_gem_vram_object *gbo,
> >   * Helpers for struct drm_gem_object_funcs
> >   */
> >  
> >  /**
> >   * drm_gem_vram_object_free() - \
> >  	Implements &struct drm_gem_object_funcs.free
> >   * @gem:       GEM object. Refers to &struct drm_gem_vram_object.gem
> >   */
> >  static void drm_gem_vram_object_free(struct drm_gem_object *gem)
> >  {
> >  	struct drm_gem_vram_object *gbo = drm_gem_vram_of_gem(gem);
> >  
> >  	drm_gem_vram_put(gbo);
> >  }
> >  
> >  /*
> >   * Helpers for dump buffers
> >   */
> >  
> >  /**
> > - * drm_gem_vram_driver_create_dumb() - \
> > + * drm_gem_vram_driver_dumb_create() - \
> >  	Implements &struct drm_driver.dumb_create
> >   * @file:		the DRM file
> >   * @dev:		the DRM device
> >   * @args:		the arguments as provided to \
> >  				&struct drm_driver.dumb_create
> >   *
> >   * This function requires the driver to use @drm_device.vram_mm for its
> >   * instance of VRAM MM.
> >   *
> >   * Returns:
> >   * 0 on success, or
> >   * a negative error code otherwise.
> >   */
> >  int drm_gem_vram_driver_dumb_create(struct drm_file *file,
> >  				    struct drm_device *dev,
> >  				    struct drm_mode_create_dumb *args)
> >  {
> >  	if (WARN_ONCE(!dev->vram_mm, "VRAM MM not initialized"))
> >  		return -EINVAL;
> >  
> > diff --git a/drivers/gpu/drm/drm_mode_object.c b/drivers/gpu/drm/drm_mode_object.c
> > index db05f386a709..b26588b52795 100644
> > --- a/drivers/gpu/drm/drm_mode_object.c
> > +++ b/drivers/gpu/drm/drm_mode_object.c
> > @@ -98,41 +98,41 @@ void drm_mode_object_register(struct drm_device *dev,
> >   * Free @id from @dev's unique identifier pool.
> >   * This function can be called multiple times, and guards against
> >   * multiple removals.
> >   * These modeset identifiers are _not_ reference counted. Hence don't use this
> >   * for reference counted modeset objects like framebuffers.
> >   */
> >  void drm_mode_object_unregister(struct drm_device *dev,
> >  				struct drm_mode_object *object)
> >  {
> >  	WARN_ON(!dev->driver->load && dev->registered && !object->free_cb);
> >  
> >  	mutex_lock(&dev->mode_config.idr_mutex);
> >  	if (object->id) {
> >  		idr_remove(&dev->mode_config.object_idr, object->id);
> >  		object->id = 0;
> >  	}
> >  	mutex_unlock(&dev->mode_config.idr_mutex);
> >  }
> >  
> >  /**
> > - * drm_lease_required - check types which must be leased to be used
> > + * drm_mode_object_lease_required - check types which must be leased to be used
> >   * @type: type of object
> >   *
> >   * Returns whether the provided type of drm_mode_object must
> >   * be owned or leased to be used by a process.
> >   */
> >  bool drm_mode_object_lease_required(uint32_t type)
> >  {
> >  	switch(type) {
> >  	case DRM_MODE_OBJECT_CRTC:
> >  	case DRM_MODE_OBJECT_CONNECTOR:
> >  	case DRM_MODE_OBJECT_PLANE:
> >  		return true;
> >  	default:
> >  		return false;
> >  	}
> >  }
> >  
> >  struct drm_mode_object *__drm_mode_object_find(struct drm_device *dev,
> >  					       struct drm_file *file_priv,
> >  					       uint32_t id, uint32_t type)
> > diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c
> > index 501b4fe55a3d..33fb2f05ce66 100644
> > --- a/drivers/gpu/drm/drm_modes.c
> > +++ b/drivers/gpu/drm/drm_modes.c
> > @@ -1872,41 +1872,41 @@ drm_mode_create_from_cmdline_mode(struct drm_device *dev,
> >  				    cmd->margins);
> >  	else
> >  		mode = drm_gtf_mode(dev,
> >  				    cmd->xres, cmd->yres,
> >  				    cmd->refresh_specified ? cmd->refresh : 60,
> >  				    cmd->interlace,
> >  				    cmd->margins);
> >  	if (!mode)
> >  		return NULL;
> >  
> >  	mode->type |= DRM_MODE_TYPE_USERDEF;
> >  	/* fix up 1368x768: GFT/CVT can't express 1366 width due to alignment */
> >  	if (cmd->xres == 1366)
> >  		drm_mode_fixup_1366x768(mode);
> >  	drm_mode_set_crtcinfo(mode, CRTC_INTERLACE_HALVE_V);
> >  	return mode;
> >  }
> >  EXPORT_SYMBOL(drm_mode_create_from_cmdline_mode);
> >  
> >  /**
> > - * drm_crtc_convert_to_umode - convert a drm_display_mode into a modeinfo
> > + * drm_mode_convert_to_umode - convert a drm_display_mode into a modeinfo
> >   * @out: drm_mode_modeinfo struct to return to the user
> >   * @in: drm_display_mode to use
> >   *
> >   * Convert a drm_display_mode into a drm_mode_modeinfo structure to return to
> >   * the user.
> >   */
> >  void drm_mode_convert_to_umode(struct drm_mode_modeinfo *out,
> >  			       const struct drm_display_mode *in)
> >  {
> >  	out->clock = in->clock;
> >  	out->hdisplay = in->hdisplay;
> >  	out->hsync_start = in->hsync_start;
> >  	out->hsync_end = in->hsync_end;
> >  	out->htotal = in->htotal;
> >  	out->hskew = in->hskew;
> >  	out->vdisplay = in->vdisplay;
> >  	out->vsync_start = in->vsync_start;
> >  	out->vsync_end = in->vsync_end;
> >  	out->vtotal = in->vtotal;
> >  	out->vscan = in->vscan;
> > @@ -1924,41 +1924,41 @@ void drm_mode_convert_to_umode(struct drm_mode_modeinfo *out,
> >  	case HDMI_PICTURE_ASPECT_64_27:
> >  		out->flags |= DRM_MODE_FLAG_PIC_AR_64_27;
> >  		break;
> >  	case HDMI_PICTURE_ASPECT_256_135:
> >  		out->flags |= DRM_MODE_FLAG_PIC_AR_256_135;
> >  		break;
> >  	default:
> >  		WARN(1, "Invalid aspect ratio (0%x) on mode\n",
> >  		     in->picture_aspect_ratio);
> >  		fallthrough;
> >  	case HDMI_PICTURE_ASPECT_NONE:
> >  		out->flags |= DRM_MODE_FLAG_PIC_AR_NONE;
> >  		break;
> >  	}
> >  
> >  	strncpy(out->name, in->name, DRM_DISPLAY_MODE_LEN);
> >  	out->name[DRM_DISPLAY_MODE_LEN-1] = 0;
> >  }
> >  
> >  /**
> > - * drm_crtc_convert_umode - convert a modeinfo into a drm_display_mode
> > + * drm_mode_convert_umode - convert a modeinfo into a drm_display_mode
> >   * @dev: drm device
> >   * @out: drm_display_mode to return to the user
> >   * @in: drm_mode_modeinfo to use
> >   *
> >   * Convert a drm_mode_modeinfo into a drm_display_mode structure to return to
> >   * the caller.
> >   *
> >   * Returns:
> >   * Zero on success, negative errno on failure.
> >   */
> >  int drm_mode_convert_umode(struct drm_device *dev,
> >  			   struct drm_display_mode *out,
> >  			   const struct drm_mode_modeinfo *in)
> >  {
> >  	if (in->clock > INT_MAX || in->vrefresh > INT_MAX)
> >  		return -ERANGE;
> >  
> >  	out->clock = in->clock;
> >  	out->hdisplay = in->hdisplay;
> >  	out->hsync_start = in->hsync_start;
> > diff --git a/drivers/gpu/drm/drm_scdc_helper.c b/drivers/gpu/drm/drm_scdc_helper.c
> > index 311e71bbba5b..991b8c86d78d 100644
> > --- a/drivers/gpu/drm/drm_scdc_helper.c
> > +++ b/drivers/gpu/drm/drm_scdc_helper.c
> > @@ -108,41 +108,41 @@ ssize_t drm_scdc_write(struct i2c_adapter *adapter, u8 offset,
> >  
> >  	msg.buf = data;
> >  
> >  	memcpy(data, &offset, sizeof(offset));
> >  	memcpy(data + 1, buffer, size);
> >  
> >  	err = i2c_transfer(adapter, &msg, 1);
> >  
> >  	kfree(data);
> >  
> >  	if (err < 0)
> >  		return err;
> >  	if (err != 1)
> >  		return -EPROTO;
> >  
> >  	return 0;
> >  }
> >  EXPORT_SYMBOL(drm_scdc_write);
> >  
> >  /**
> > - * drm_scdc_check_scrambling_status - what is status of scrambling?
> > + * drm_scdc_get_scrambling_status - what is status of scrambling?
> >   * @adapter: I2C adapter for DDC channel
> >   *
> >   * Reads the scrambler status over SCDC, and checks the
> >   * scrambling status.
> >   *
> >   * Returns:
> >   * True if the scrambling is enabled, false otherwise.
> >   */
> >  bool drm_scdc_get_scrambling_status(struct i2c_adapter *adapter)
> >  {
> >  	u8 status;
> >  	int ret;
> >  
> >  	ret = drm_scdc_readb(adapter, SCDC_SCRAMBLER_STATUS, &status);
> >  	if (ret < 0) {
> >  		DRM_DEBUG_KMS("Failed to read scrambling status: %d\n", ret);
> >  		return false;
> >  	}
> >  
> >  	return status & SCDC_SCRAMBLING_STATUS;
> > diff --git a/drivers/gpu/drm/i915/display/intel_dpll_mgr.c b/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
> > index a95e6a2ac698..8753bab20ce8 100644
> > --- a/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
> > +++ b/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
> > @@ -4573,41 +4573,41 @@ static void sanitize_dpll_state(struct drm_i915_private *i915,
> >  	if (!pll->on || pll->active_mask)
> >  		return;
> >  
> >  	drm_dbg_kms(&i915->drm,
> >  		    "%s enabled but not in use, disabling\n",
> >  		    pll->info->name);
> >  
> >  	pll->info->funcs->disable(i915, pll);
> >  	pll->on = false;
> >  }
> >  
> >  void intel_dpll_sanitize_state(struct drm_i915_private *i915)
> >  {
> >  	int i;
> >  
> >  	for (i = 0; i < i915->dpll.num_shared_dpll; i++)
> >  		sanitize_dpll_state(i915, &i915->dpll.shared_dplls[i]);
> >  }
> >  
> >  /**
> > - * intel_shared_dpll_dump_hw_state - write hw_state to dmesg
> > + * intel_dpll_dump_hw_state - write hw_state to dmesg
> >   * @dev_priv: i915 drm device
> >   * @hw_state: hw state to be written to the log
> >   *
> >   * Write the relevant values in @hw_state to dmesg using drm_dbg_kms.
> >   */
> >  void intel_dpll_dump_hw_state(struct drm_i915_private *dev_priv,
> >  			      const struct intel_dpll_hw_state *hw_state)
> >  {
> >  	if (dev_priv->dpll.mgr) {
> >  		dev_priv->dpll.mgr->dump_hw_state(dev_priv, hw_state);
> >  	} else {
> >  		/* fallback for platforms that don't use the shared dpll
> >  		 * infrastructure
> >  		 */
> >  		drm_dbg_kms(&dev_priv->drm,
> >  			    "dpll_hw_state: dpll: 0x%x, dpll_md: 0x%x, "
> >  			    "fp0: 0x%x, fp1: 0x%x\n",
> >  			    hw_state->dpll,
> >  			    hw_state->dpll_md,
> >  			    hw_state->fp0,
> > diff --git a/drivers/gpu/drm/i915/i915_gem_evict.c b/drivers/gpu/drm/i915/i915_gem_evict.c
> > index 6501939929d5..e1a66c8245b8 100644
> > --- a/drivers/gpu/drm/i915/i915_gem_evict.c
> > +++ b/drivers/gpu/drm/i915/i915_gem_evict.c
> > @@ -221,41 +221,41 @@ i915_gem_evict_something(struct i915_address_space *vm,
> >  	list_for_each_entry_safe(vma, next, &eviction_list, evict_link) {
> >  		__i915_vma_unpin(vma);
> >  		if (ret == 0)
> >  			ret = __i915_vma_unbind(vma);
> >  	}
> >  
> >  	while (ret == 0 && (node = drm_mm_scan_color_evict(&scan))) {
> >  		vma = container_of(node, struct i915_vma, node);
> >  
> >  		/* If we find any non-objects (!vma), we cannot evict them */
> >  		if (vma->node.color != I915_COLOR_UNEVICTABLE)
> >  			ret = __i915_vma_unbind(vma);
> >  		else
> >  			ret = -ENOSPC; /* XXX search failed, try again? */
> >  	}
> >  
> >  	return ret;
> >  }
> >  
> >  /**
> > - * i915_gem_evict_for_vma - Evict vmas to make room for binding a new one
> > + * i915_gem_evict_for_node - Evict vmas to make room for binding a new one
> >   * @vm: address space to evict from
> >   * @target: range (and color) to evict for
> >   * @flags: additional flags to control the eviction algorithm
> >   *
> >   * This function will try to evict vmas that overlap the target node.
> >   *
> >   * To clarify: This is for freeing up virtual address space, not for freeing
> >   * memory in e.g. the shrinker.
> >   */
> >  int i915_gem_evict_for_node(struct i915_address_space *vm,
> >  			    struct drm_mm_node *target,
> >  			    unsigned int flags)
> >  {
> >  	LIST_HEAD(eviction_list);
> >  	struct drm_mm_node *node;
> >  	u64 start = target->start;
> >  	u64 end = start + target->size;
> >  	struct i915_vma *vma, *next;
> >  	int ret = 0;
> >  
> > diff --git a/drivers/gpu/drm/i915/i915_perf.c b/drivers/gpu/drm/i915/i915_perf.c
> > index e94976976571..3ced82820483 100644
> > --- a/drivers/gpu/drm/i915/i915_perf.c
> > +++ b/drivers/gpu/drm/i915/i915_perf.c
> > @@ -608,41 +608,42 @@ static int append_oa_sample(struct i915_perf_stream *stream,
> >  
> >  	if ((count - *offset) < header.size)
> >  		return -ENOSPC;
> >  
> >  	buf += *offset;
> >  	if (copy_to_user(buf, &header, sizeof(header)))
> >  		return -EFAULT;
> >  	buf += sizeof(header);
> >  
> >  	if (sample_flags & SAMPLE_OA_REPORT) {
> >  		if (copy_to_user(buf, report, report_size))
> >  			return -EFAULT;
> >  	}
> >  
> >  	(*offset) += header.size;
> >  
> >  	return 0;
> >  }
> >  
> >  /**
> > - * Copies all buffered OA reports into userspace read() buffer.
> > + * gen8_append_oa_reports - Copies all buffered OA reports into
> > + *			    userspace read() buffer.
> >   * @stream: An i915-perf stream opened for OA metrics
> >   * @buf: destination buffer given by userspace
> >   * @count: the number of bytes userspace wants to read
> >   * @offset: (inout): the current position for writing into @buf
> >   *
> >   * Notably any error condition resulting in a short read (-%ENOSPC or
> >   * -%EFAULT) will be returned even though one or more records may
> >   * have been successfully copied. In this case it's up to the caller
> >   * to decide if the error should be squashed before returning to
> >   * userspace.
> >   *
> >   * Note: reports are consumed from the head, and appended to the
> >   * tail, so the tail chases the head?... If you think that's mad
> >   * and back-to-front you're not alone, but this follows the
> >   * Gen PRM naming convention.
> >   *
> >   * Returns: 0 on success, negative error code on failure.
> >   */
> >  static int gen8_append_oa_reports(struct i915_perf_stream *stream,
> >  				  char __user *buf,
> > @@ -900,41 +901,42 @@ static int gen8_oa_read(struct i915_perf_stream *stream,
> >  		/*
> >  		 * Note: .oa_enable() is expected to re-init the oabuffer and
> >  		 * reset GEN8_OASTATUS for us
> >  		 */
> >  		oastatus = intel_uncore_read(uncore, oastatus_reg);
> >  	}
> >  
> >  	if (oastatus & GEN8_OASTATUS_REPORT_LOST) {
> >  		ret = append_oa_status(stream, buf, count, offset,
> >  				       DRM_I915_PERF_RECORD_OA_REPORT_LOST);
> >  		if (ret)
> >  			return ret;
> >  		intel_uncore_write(uncore, oastatus_reg,
> >  				   oastatus & ~GEN8_OASTATUS_REPORT_LOST);
> >  	}
> >  
> >  	return gen8_append_oa_reports(stream, buf, count, offset);
> >  }
> >  
> >  /**
> > - * Copies all buffered OA reports into userspace read() buffer.
> > + * gen7_append_oa_reports - Copies all buffered OA reports into
> > + *			    userspace read() buffer.
> >   * @stream: An i915-perf stream opened for OA metrics
> >   * @buf: destination buffer given by userspace
> >   * @count: the number of bytes userspace wants to read
> >   * @offset: (inout): the current position for writing into @buf
> >   *
> >   * Notably any error condition resulting in a short read (-%ENOSPC or
> >   * -%EFAULT) will be returned even though one or more records may
> >   * have been successfully copied. In this case it's up to the caller
> >   * to decide if the error should be squashed before returning to
> >   * userspace.
> >   *
> >   * Note: reports are consumed from the head, and appended to the
> >   * tail, so the tail chases the head?... If you think that's mad
> >   * and back-to-front you're not alone, but this follows the
> >   * Gen PRM naming convention.
> >   *
> >   * Returns: 0 on success, negative error code on failure.
> >   */
> >  static int gen7_append_oa_reports(struct i915_perf_stream *stream,
> >  				  char __user *buf,
> > @@ -3210,41 +3212,41 @@ static long i915_perf_config_locked(struct i915_perf_stream *stream,
> >  		 * reconfiguration inline from that context. The update
> >  		 * will then be ordered with respect to submission on that
> >  		 * context.
> >  		 *
> >  		 * When set globally, we use a low priority kernel context,
> >  		 * so it will effectively take effect when idle.
> >  		 */
> >  		err = emit_oa_config(stream, config, oa_context(stream), NULL);
> >  		if (!err)
> >  			config = xchg(&stream->oa_config, config);
> >  		else
> >  			ret = err;
> >  	}
> >  
> >  	i915_oa_config_put(config);
> >  
> >  	return ret;
> >  }
> >  
> >  /**
> > - * i915_perf_ioctl - support ioctl() usage with i915 perf stream FDs
> > + * i915_perf_ioctl_locked - support ioctl() usage with i915 perf stream FDs
> >   * @stream: An i915 perf stream
> >   * @cmd: the ioctl request
> >   * @arg: the ioctl data
> >   *
> >   * Note: The &perf->lock mutex has been taken to serialize
> >   * with any non-file-operation driver hooks.
> >   *
> >   * Returns: zero on success or a negative error code. Returns -EINVAL for
> >   * an unknown ioctl request.
> >   */
> >  static long i915_perf_ioctl_locked(struct i915_perf_stream *stream,
> >  				   unsigned int cmd,
> >  				   unsigned long arg)
> >  {
> >  	switch (cmd) {
> >  	case I915_PERF_IOCTL_ENABLE:
> >  		i915_perf_enable_locked(stream);
> >  		return 0;
> >  	case I915_PERF_IOCTL_DISABLE:
> >  		i915_perf_disable_locked(stream);
> > diff --git a/drivers/gpu/drm/scheduler/sched_main.c b/drivers/gpu/drm/scheduler/sched_main.c
> > index da24c4e8b9fb..b498d474ef9e 100644
> > --- a/drivers/gpu/drm/scheduler/sched_main.c
> > +++ b/drivers/gpu/drm/scheduler/sched_main.c
> > @@ -430,41 +430,41 @@ void drm_sched_stop(struct drm_gpu_scheduler *sched, struct drm_sched_job *bad)
> >  			 */
> >  			if (bad != s_job)
> >  				sched->ops->free_job(s_job);
> >  			else
> >  				sched->free_guilty = true;
> >  		}
> >  	}
> >  
> >  	/*
> >  	 * Stop pending timer in flight as we rearm it in  drm_sched_start. This
> >  	 * avoids the pending timeout work in progress to fire right away after
> >  	 * this TDR finished and before the newly restarted jobs had a
> >  	 * chance to complete.
> >  	 */
> >  	cancel_delayed_work(&sched->work_tdr);
> >  }
> >  
> >  EXPORT_SYMBOL(drm_sched_stop);
> >  
> >  /**
> > - * drm_sched_job_recovery - recover jobs after a reset
> > + * drm_sched_start - recover jobs after a reset
> >   *
> >   * @sched: scheduler instance
> >   * @full_recovery: proceed with complete sched restart
> >   *
> >   */
> >  void drm_sched_start(struct drm_gpu_scheduler *sched, bool full_recovery)
> >  {
> >  	struct drm_sched_job *s_job, *tmp;
> >  	int r;
> >  
> >  	/*
> >  	 * Locking the list is not required here as the sched thread is parked
> >  	 * so no new jobs are being inserted or removed. Also concurrent
> >  	 * GPU recovers can't run in parallel.
> >  	 */
> >  	list_for_each_entry_safe(s_job, tmp, &sched->ring_mirror_list, node) {
> >  		struct dma_fence *fence = s_job->s_fence->parent;
> >  
> >  		atomic_inc(&sched->hw_rq_count);
> >  
> > diff --git a/drivers/gpu/drm/v3d/v3d_sched.c b/drivers/gpu/drm/v3d/v3d_sched.c
> > index 0747614a78f0..f968f389633a 100644
> > --- a/drivers/gpu/drm/v3d/v3d_sched.c
> > +++ b/drivers/gpu/drm/v3d/v3d_sched.c
> > @@ -47,41 +47,41 @@ to_tfu_job(struct drm_sched_job *sched_job)
> >  {
> >  	return container_of(sched_job, struct v3d_tfu_job, base.base);
> >  }
> >  
> >  static struct v3d_csd_job *
> >  to_csd_job(struct drm_sched_job *sched_job)
> >  {
> >  	return container_of(sched_job, struct v3d_csd_job, base.base);
> >  }
> >  
> >  static void
> >  v3d_job_free(struct drm_sched_job *sched_job)
> >  {
> >  	struct v3d_job *job = to_v3d_job(sched_job);
> >  
> >  	drm_sched_job_cleanup(sched_job);
> >  	v3d_job_put(job);
> >  }
> >  
> >  /**
> > - * Returns the fences that the job depends on, one by one.
> > + * v3d_job_dependency - Returns the fences that the job depends on, one by one.
> >   *
> >   * If placed in the scheduler's .dependency method, the corresponding
> >   * .run_job won't be called until all of them have been signaled.
> >   */
> >  static struct dma_fence *
> >  v3d_job_dependency(struct drm_sched_job *sched_job,
> >  		   struct drm_sched_entity *s_entity)
> >  {
> >  	struct v3d_job *job = to_v3d_job(sched_job);
> >  
> >  	/* XXX: Wait on a fence for switching the GMP if necessary,
> >  	 * and then do so.
> >  	 */
> >  
> >  	if (!xa_empty(&job->deps))
> >  		return xa_erase(&job->deps, job->last_dep++);
> >  
> >  	return NULL;
> >  }
> >  
> > diff --git a/drivers/gpu/drm/vc4/vc4_bo.c b/drivers/gpu/drm/vc4/vc4_bo.c
> > index a21a6c53ffcf..469d1b4f2643 100644
> > --- a/drivers/gpu/drm/vc4/vc4_bo.c
> > +++ b/drivers/gpu/drm/vc4/vc4_bo.c
> > @@ -374,41 +374,41 @@ static struct vc4_bo *vc4_bo_get_from_cache(struct drm_device *dev,
> >  		vc4_bo_set_label(&bo->base.base, type);
> >  	mutex_unlock(&vc4->bo_lock);
> >  	return bo;
> >  }
> >  
> >  static const struct vm_operations_struct vc4_vm_ops = {
> >  	.fault = vc4_fault,
> >  	.open = drm_gem_vm_open,
> >  	.close = drm_gem_vm_close,
> >  };
> >  
> >  static const struct drm_gem_object_funcs vc4_gem_object_funcs = {
> >  	.free = vc4_free_object,
> >  	.export = vc4_prime_export,
> >  	.get_sg_table = drm_gem_cma_prime_get_sg_table,
> >  	.vmap = vc4_prime_vmap,
> >  	.vm_ops = &vc4_vm_ops,
> >  };
> >  
> >  /**
> > - * vc4_gem_create_object - Implementation of driver->gem_create_object.
> > + * vc4_create_object - Implementation of driver->gem_create_object.
> >   * @dev: DRM device
> >   * @size: Size in bytes of the memory the object will reference
> >   *
> >   * This lets the CMA helpers allocate object structs for us, and keep
> >   * our BO stats correct.
> >   */
> >  struct drm_gem_object *vc4_create_object(struct drm_device *dev, size_t size)
> >  {
> >  	struct vc4_dev *vc4 = to_vc4_dev(dev);
> >  	struct vc4_bo *bo;
> >  
> >  	bo = kzalloc(sizeof(*bo), GFP_KERNEL);
> >  	if (!bo)
> >  		return ERR_PTR(-ENOMEM);
> >  
> >  	bo->madv = VC4_MADV_WILLNEED;
> >  	refcount_set(&bo->usecnt, 0);
> >  	mutex_init(&bo->madv_lock);
> >  	mutex_lock(&vc4->bo_lock);
> >  	bo->label = VC4_BO_TYPE_KERNEL;
> > diff --git a/include/drm/drm_atomic_helper.h b/include/drm/drm_atomic_helper.h
> > index 85df04c8e62f..5f47720440fa 100644
> > --- a/include/drm/drm_atomic_helper.h
> > +++ b/include/drm/drm_atomic_helper.h
> > @@ -150,54 +150,54 @@ int drm_atomic_helper_page_flip_target(
> >  int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc,
> >  				       u16 *red, u16 *green, u16 *blue,
> >  				       uint32_t size,
> >  				       struct drm_modeset_acquire_ctx *ctx);
> >  
> >  /**
> >   * drm_atomic_crtc_for_each_plane - iterate over planes currently attached to CRTC
> >   * @plane: the loop cursor
> >   * @crtc:  the CRTC whose planes are iterated
> >   *
> >   * This iterates over the current state, useful (for example) when applying
> >   * atomic state after it has been checked and swapped.  To iterate over the
> >   * planes which *will* be attached (more useful in code called from
> >   * &drm_mode_config_funcs.atomic_check) see
> >   * drm_atomic_crtc_state_for_each_plane().
> >   */
> >  #define drm_atomic_crtc_for_each_plane(plane, crtc) \
> >  	drm_for_each_plane_mask(plane, (crtc)->dev, (crtc)->state->plane_mask)
> >  
> >  /**
> > - * drm_crtc_atomic_state_for_each_plane - iterate over attached planes in new state
> > + * drm_atomic_crtc_state_for_each_plane - iterate over attached planes in new state
> >   * @plane: the loop cursor
> >   * @crtc_state: the incoming CRTC state
> >   *
> >   * Similar to drm_crtc_for_each_plane(), but iterates the planes that will be
> >   * attached if the specified state is applied.  Useful during for example
> >   * in code called from &drm_mode_config_funcs.atomic_check operations, to
> >   * validate the incoming state.
> >   */
> >  #define drm_atomic_crtc_state_for_each_plane(plane, crtc_state) \
> >  	drm_for_each_plane_mask(plane, (crtc_state)->state->dev, (crtc_state)->plane_mask)
> >  
> >  /**
> > - * drm_crtc_atomic_state_for_each_plane_state - iterate over attached planes in new state
> > + * drm_atomic_crtc_state_for_each_plane_state - iterate over attached planes in new state
> >   * @plane: the loop cursor
> >   * @plane_state: loop cursor for the plane's state, must be const
> >   * @crtc_state: the incoming CRTC state
> >   *
> >   * Similar to drm_crtc_for_each_plane(), but iterates the planes that will be
> >   * attached if the specified state is applied.  Useful during for example
> >   * in code called from &drm_mode_config_funcs.atomic_check operations, to
> >   * validate the incoming state.
> >   *
> >   * Compared to just drm_atomic_crtc_state_for_each_plane() this also fills in a
> >   * const plane_state. This is useful when a driver just wants to peek at other
> >   * active planes on this CRTC, but does not need to change it.
> >   */
> >  #define drm_atomic_crtc_state_for_each_plane_state(plane, plane_state, crtc_state) \
> >  	drm_for_each_plane_mask(plane, (crtc_state)->state->dev, (crtc_state)->plane_mask) \
> >  		for_each_if ((plane_state = \
> >  			      __drm_atomic_get_current_plane_state((crtc_state)->state, \
> >  								   plane)))
> >  
> >  /**
> > diff --git a/include/drm/drm_connector.h b/include/drm/drm_connector.h
> > index 928136556174..fcdc58d8b88b 100644
> > --- a/include/drm/drm_connector.h
> > +++ b/include/drm/drm_connector.h
> > @@ -67,41 +67,41 @@ enum drm_connector_status {
> >  	 * sink device which can be autodetect. For digital outputs like DP or
> >  	 * HDMI (which can be realiable probed) this means there's really
> >  	 * nothing there. It is driver-dependent whether a connector with this
> >  	 * status can be lit up or not.
> >  	 */
> >  	connector_status_disconnected = 2,
> >  	/**
> >  	 * @connector_status_unknown: The connector's status could not be
> >  	 * reliably detected. This happens when probing would either cause
> >  	 * flicker (like load-detection when the connector is in use), or when a
> >  	 * hardware resource isn't available (like when load-detection needs a
> >  	 * free CRTC). It should be possible to light up the connector with one
> >  	 * of the listed fallback modes. For default configuration userspace
> >  	 * should only try to light up connectors with unknown status when
> >  	 * there's not connector with @connector_status_connected.
> >  	 */
> >  	connector_status_unknown = 3,
> >  };
> >  
> >  /**
> > - * enum drm_connector_registration_status - userspace registration status for
> > + * enum drm_connector_registration_state - userspace registration status for
> >   * a &drm_connector
> >   *
> >   * This enum is used to track the status of initializing a connector and
> >   * registering it with userspace, so that DRM can prevent bogus modesets on
> >   * connectors that no longer exist.
> >   */
> >  enum drm_connector_registration_state {
> >  	/**
> >  	 * @DRM_CONNECTOR_INITIALIZING: The connector has just been created,
> >  	 * but has yet to be exposed to userspace. There should be no
> >  	 * additional restrictions to how the state of this connector may be
> >  	 * modified.
> >  	 */
> >  	DRM_CONNECTOR_INITIALIZING = 0,
> >  
> >  	/**
> >  	 * @DRM_CONNECTOR_REGISTERED: The connector has been fully initialized
> >  	 * and registered with sysfs, as such it has been exposed to
> >  	 * userspace. There should be no additional restrictions to how the
> >  	 * state of this connector may be modified.
> > diff --git a/include/drm/drm_device.h b/include/drm/drm_device.h
> > index 2c361964aee7..283a93ce4617 100644
> > --- a/include/drm/drm_device.h
> > +++ b/include/drm/drm_device.h
> > @@ -10,41 +10,41 @@
> >  #include <drm/drm_mode_config.h>
> >  
> >  struct drm_driver;
> >  struct drm_minor;
> >  struct drm_master;
> >  struct drm_device_dma;
> >  struct drm_vblank_crtc;
> >  struct drm_sg_mem;
> >  struct drm_local_map;
> >  struct drm_vma_offset_manager;
> >  struct drm_vram_mm;
> >  struct drm_fb_helper;
> >  
> >  struct inode;
> >  
> >  struct pci_dev;
> >  struct pci_controller;
> >  
> >  
> >  /**
> > - * enum drm_switch_power - power state of drm device
> > + * enum switch_power_state - power state of drm device
> >   */
> >  
> >  enum switch_power_state {
> >  	/** @DRM_SWITCH_POWER_ON: Power state is ON */
> >  	DRM_SWITCH_POWER_ON = 0,
> >  
> >  	/** @DRM_SWITCH_POWER_OFF: Power state is OFF */
> >  	DRM_SWITCH_POWER_OFF = 1,
> >  
> >  	/** @DRM_SWITCH_POWER_CHANGING: Power state is changing */
> >  	DRM_SWITCH_POWER_CHANGING = 2,
> >  
> >  	/** @DRM_SWITCH_POWER_DYNAMIC_OFF: Suspended */
> >  	DRM_SWITCH_POWER_DYNAMIC_OFF = 3,
> >  };
> >  
> >  /**
> >   * struct drm_device - DRM device structure
> >   *
> >   * This structure represent a complete card that
> > diff --git a/include/drm/drm_dsc.h b/include/drm/drm_dsc.h
> > index 732f32740c86..53c51231b31c 100644
> > --- a/include/drm/drm_dsc.h
> > +++ b/include/drm/drm_dsc.h
> > @@ -256,41 +256,42 @@ struct drm_dsc_config {
> >  	bool native_420;
> >  	/**
> >  	 * @second_line_bpg_offset:
> >  	 * Additional bits/grp for seconnd line of slice for native 4:2:0
> >  	 */
> >  	u8 second_line_bpg_offset;
> >  	/**
> >  	 * @nsl_bpg_offset:
> >  	 * Num of bits deallocated for each grp that is not in second line of
> >  	 * slice
> >  	 */
> >  	u16 nsl_bpg_offset;
> >  	/**
> >  	 * @second_line_offset_adj:
> >  	 * Offset adjustment for second line in Native 4:2:0 mode
> >  	 */
> >  	u16 second_line_offset_adj;
> >  };
> >  
> >  /**
> > - * struct picture_parameter_set - Represents 128 bytes of Picture Parameter Set
> > + * struct drm_dsc_picture_parameter_set - Represents 128 bytes of
> > + * 	Picture Parameter Set
> >   *
> >   * The VESA DSC standard defines picture parameter set (PPS) which display
> >   * stream compression encoders must communicate to decoders.
> >   * The PPS is encapsulated in 128 bytes (PPS 0 through PPS 127). The fields in
> >   * this structure are as per Table 4.1 in Vesa DSC specification v1.1/v1.2.
> >   * The PPS fields that span over more than a byte should be stored in Big Endian
> >   * format.
> >   */
> >  struct drm_dsc_picture_parameter_set {
> >  	/**
> >  	 * @dsc_version:
> >  	 * PPS0[3:0] - dsc_version_minor: Contains Minor version of DSC
> >  	 * PPS0[7:4] - dsc_version_major: Contains major version of DSC
> >  	 */
> >  	u8 dsc_version;
> >  	/**
> >  	 * @pps_identifier:
> >  	 * PPS1[7:0] - Application specific identifier that can be
> >  	 * used to differentiate between different PPS tables.
> >  	 */
> > diff --git a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h
> > index c0d28ba0f5c9..a4bac02249c2 100644
> > --- a/include/drm/drm_gem_vram_helper.h
> > +++ b/include/drm/drm_gem_vram_helper.h
> > @@ -49,54 +49,54 @@ struct vm_area_struct;
> >   * drm_gem_vram_vmap() and drm_gem_vram_vunmap().
> >   */
> >  struct drm_gem_vram_object {
> >  	struct ttm_buffer_object bo;
> >  	struct dma_buf_map map;
> >  
> >  	/**
> >  	 * @vmap_use_count:
> >  	 *
> >  	 * Reference count on the virtual address.
> >  	 * The address are un-mapped when the count reaches zero.
> >  	 */
> >  	unsigned int vmap_use_count;
> >  
> >  	/* Supported placements are %TTM_PL_VRAM and %TTM_PL_SYSTEM */
> >  	struct ttm_placement placement;
> >  	struct ttm_place placements[2];
> >  };
> >  
> >  /**
> > - * Returns the container of type &struct drm_gem_vram_object
> > - * for field bo.
> > + * drm_gem_vram_of_bo - Returns the container of type
> > + * &struct drm_gem_vram_object for field bo.
> >   * @bo:		the VRAM buffer object
> >   * Returns:	The containing GEM VRAM object
> >   */
> >  static inline struct drm_gem_vram_object *drm_gem_vram_of_bo(
> >  	struct ttm_buffer_object *bo)
> >  {
> >  	return container_of(bo, struct drm_gem_vram_object, bo);
> >  }
> >  
> >  /**
> > - * Returns the container of type &struct drm_gem_vram_object
> > - * for field gem.
> > + * drm_gem_vram_of_gem - Returns the container of type
> > + * &struct drm_gem_vram_object for field gem.
> >   * @gem:	the GEM object
> >   * Returns:	The containing GEM VRAM object
> >   */
> >  static inline struct drm_gem_vram_object *drm_gem_vram_of_gem(
> >  	struct drm_gem_object *gem)
> >  {
> >  	return container_of(gem, struct drm_gem_vram_object, bo.base);
> >  }
> >  
> >  struct drm_gem_vram_object *drm_gem_vram_create(struct drm_device *dev,
> >  						size_t size,
> >  						unsigned long pg_align);
> >  void drm_gem_vram_put(struct drm_gem_vram_object *gbo);
> >  u64 drm_gem_vram_mmap_offset(struct drm_gem_vram_object *gbo);
> >  s64 drm_gem_vram_offset(struct drm_gem_vram_object *gbo);
> >  int drm_gem_vram_pin(struct drm_gem_vram_object *gbo, unsigned long pl_flag);
> >  int drm_gem_vram_unpin(struct drm_gem_vram_object *gbo);
> >  int drm_gem_vram_vmap(struct drm_gem_vram_object *gbo, struct dma_buf_map *map);
> >  void drm_gem_vram_vunmap(struct drm_gem_vram_object *gbo, struct dma_buf_map *map);
> 
> -- 
> Jani Nikula, Intel Open Source Graphics Center

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 20/27] list: fix a typo at the kernel-doc markup
  2020-11-16 10:18 ` [PATCH v4 20/27] list: fix a typo at the kernel-doc markup Mauro Carvalho Chehab
@ 2020-11-16 19:57   ` Paul E. McKenney
  0 siblings, 0 replies; 51+ messages in thread
From: Paul E. McKenney @ 2020-11-16 19:57 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Jonathan Corbet, Andrew Morton,
	Andy Shevchenko, Asif Rasheed, Eric Dumazet, Pavel Begunkov,
	linux-kernel

On Mon, Nov 16, 2020 at 11:18:16AM +0100, Mauro Carvalho Chehab wrote:
> hlist_add_behing -> hlist_add_behind
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Queued, thank you!

Or if you would prefer pushing it yourself:

Reviewed-by: Paul E. McKenney <paulmck@kernel.org>

Either way, please let me know.

							Thanx, Paul

> ---
>  include/linux/list.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/linux/list.h b/include/linux/list.h
> index 89bdc92e75c3..f2af4b4aa4e9 100644
> --- a/include/linux/list.h
> +++ b/include/linux/list.h
> @@ -884,41 +884,41 @@ static inline void hlist_add_head(struct hlist_node *n, struct hlist_head *h)
>  		WRITE_ONCE(first->pprev, &n->next);
>  	WRITE_ONCE(h->first, n);
>  	WRITE_ONCE(n->pprev, &h->first);
>  }
>  
>  /**
>   * hlist_add_before - add a new entry before the one specified
>   * @n: new entry to be added
>   * @next: hlist node to add it before, which must be non-NULL
>   */
>  static inline void hlist_add_before(struct hlist_node *n,
>  				    struct hlist_node *next)
>  {
>  	WRITE_ONCE(n->pprev, next->pprev);
>  	WRITE_ONCE(n->next, next);
>  	WRITE_ONCE(next->pprev, &n->next);
>  	WRITE_ONCE(*(n->pprev), n);
>  }
>  
>  /**
> - * hlist_add_behing - add a new entry after the one specified
> + * hlist_add_behind - add a new entry after the one specified
>   * @n: new entry to be added
>   * @prev: hlist node to add it after, which must be non-NULL
>   */
>  static inline void hlist_add_behind(struct hlist_node *n,
>  				    struct hlist_node *prev)
>  {
>  	WRITE_ONCE(n->next, prev->next);
>  	WRITE_ONCE(prev->next, n);
>  	WRITE_ONCE(n->pprev, &prev->next);
>  
>  	if (n->next)
>  		WRITE_ONCE(n->next->pprev, &n->next);
>  }
>  
>  /**
>   * hlist_add_fake - create a fake hlist consisting of a single headless node
>   * @n: Node to make a fake list out of
>   *
>   * This makes @n appear to be its own predecessor on a headless hlist.
>   * The point of this is to allow things like hlist_del() to work correctly
> -- 
> 2.28.0
> 

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 00/27]Fix several bad kernel-doc markups
  2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
                   ` (26 preceding siblings ...)
  2020-11-16 10:18 ` [PATCH v4 27/27] scripts: kernel-doc: validate kernel-doc markup with the actual names Mauro Carvalho Chehab
@ 2020-11-17 22:19 ` Jakub Kicinski
  27 siblings, 0 replies; 51+ messages in thread
From: Jakub Kicinski @ 2020-11-17 22:19 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, linux-kernel, Jonathan Corbet,
	David S. Miller, Theodore Ts'o, Alexander Viro,
	Alexandre Bounine, Andrew Lunn, Andrew Morton, Andy Lutomirski,
	Anna Schumaker, Anton Vorontsov, Ben Segall, Colin Cross,
	Daniel Bristot de Oliveira, Daniel Vetter, David Airlie,
	Dietmar Eggemann, Evgeniy Polyakov, Heiner Kallweit, Ingo Molnar,
	Jan Kara, Juri Lelli, Kees Cook, Maarten Lankhorst, Matt Porter,
	Maxime Ripard, Mel Gorman, Mike Rapoport, Peter Zijlstra,
	Richard Gong, Russell King, Sebastian Reichel, Shuah Khan,
	Steven Rostedt, Sudip Mukherjee, Thomas Gleixner,
	Thomas Zimmermann, Tony Luck, Trond Myklebust, Vincent Guittot,
	Will Drewry, dri-devel, intel-gfx, linux-ext4, linux-fbdev,
	linux-fsdevel, linux-kselftest, linux-mm, linux-nfs, linux-rdma,
	linux-s390, netdev, target-devel

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!

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 12/27] jbd2: fix kernel-doc markups
  2020-11-16 10:18 ` [PATCH v4 12/27] jbd2: " Mauro Carvalho Chehab
@ 2020-11-20  3:38   ` Theodore Y. Ts'o
  0 siblings, 0 replies; 51+ messages in thread
From: Theodore Y. Ts'o @ 2020-11-20  3:38 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Jan Kara, Jonathan Corbet, Linux Doc Mailing List, linux-ext4,
	linux-kernel, Jan Kara

On Mon, Nov 16, 2020 at 11:18:08AM +0100, Mauro Carvalho Chehab wrote:
> Kernel-doc markup should use this format:
>         identifier - description
> 
> They should not have any type before that, as otherwise
> the parser won't do the right thing.
> 
> Also, some identifiers have different names between their
> prototypes and the kernel-doc markup.
> 
> Reviewed-by: Jan Kara <jack@suse.cz>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Applied to the ext4 tree, thanks!

					- Ted

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 07/27] IB: fix kernel-doc markups
  2020-11-16 10:18 ` [PATCH v4 07/27] IB: fix kernel-doc markups Mauro Carvalho Chehab
  2020-11-16 10:36   ` Gustavo A. R. Silva
@ 2020-11-23 23:45   ` Jason Gunthorpe
  2020-12-01 11:39     ` Mauro Carvalho Chehab
  1 sibling, 1 reply; 51+ messages in thread
From: Jason Gunthorpe @ 2020-11-23 23:45 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Gustavo A. R. Silva, Håkon Bugge,
	Jonathan Corbet, Bart Van Assche, Chuck Lever, Danit Goldberg,
	Dennis Dalessandro, Divya Indi, Doug Ledford, Gal Pressman,
	Leon Romanovsky, Maor Gottlieb, Max Gurtovoy, Mike Marciniszyn,
	Moni Shoua, Or Gerlitz, Parav Pandit, Sagi Grimberg,
	Ursula Braun, Xi Wang, Yamin Friedman, linux-kernel, linux-rdma,
	target-devel

On Mon, Nov 16, 2020 at 11:18:03AM +0100, Mauro Carvalho Chehab wrote:

> +/**
> + * ib_alloc_pd - Allocates an unused protection domain.
> + * @device: The device on which to allocate the protection domain.
> + * @flags: protection domain flags
> + *
> + * A protection domain object provides an association between QPs, shared
> + * receive queues, address handles, memory regions, and memory windows.
> + *
> + * Every PD has a local_dma_lkey which can be used as the lkey value for local
> + * memory operations.
> + */
>  #define ib_alloc_pd(device, flags) \
>  	__ib_alloc_pd((device), (flags), KBUILD_MODNAME)

Why this hunk adding a completely new description in this patch?

Jason

^ permalink raw reply	[flat|nested] 51+ messages in thread

* Re: [PATCH v4 07/27] IB: fix kernel-doc markups
  2020-11-23 23:45   ` Jason Gunthorpe
@ 2020-12-01 11:39     ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 51+ messages in thread
From: Mauro Carvalho Chehab @ 2020-12-01 11:39 UTC (permalink / raw)
  To: Jason Gunthorpe
  Cc: Linux Doc Mailing List, Gustavo A. R. Silva, Håkon Bugge,
	Jonathan Corbet, Bart Van Assche, Chuck Lever, Danit Goldberg,
	Dennis Dalessandro, Divya Indi, Doug Ledford, Gal Pressman,
	Leon Romanovsky, Maor Gottlieb, Max Gurtovoy, Mike Marciniszyn,
	Moni Shoua, Or Gerlitz, Parav Pandit, Sagi Grimberg,
	Ursula Braun, Xi Wang, Yamin Friedman, linux-kernel, linux-rdma,
	target-devel

Em Mon, 23 Nov 2020 19:45:42 -0400
Jason Gunthorpe <jgg@nvidia.com> escreveu:

> On Mon, Nov 16, 2020 at 11:18:03AM +0100, Mauro Carvalho Chehab wrote:
> 
> > +/**
> > + * ib_alloc_pd - Allocates an unused protection domain.
> > + * @device: The device on which to allocate the protection domain.
> > + * @flags: protection domain flags
> > + *
> > + * A protection domain object provides an association between QPs, shared
> > + * receive queues, address handles, memory regions, and memory windows.
> > + *
> > + * Every PD has a local_dma_lkey which can be used as the lkey value for local
> > + * memory operations.
> > + */
> >  #define ib_alloc_pd(device, flags) \
> >  	__ib_alloc_pd((device), (flags), KBUILD_MODNAME)  
> 
> Why this hunk adding a completely new description in this patch?

In order to document ib_alloc_pd().

See, currently, verbs.c has this kernel-doc markup:

	/**
	 * ib_alloc_pd - Allocates an unused protection domain.
	 * @device: The device on which to allocate the protection domain.
	 * @flags: protection domain flags
	 * @caller: caller's build-time module name
	 *
	 * A protection domain object provides an association between QPs, shared
	 * receive queues, address handles, memory regions, and memory windows.
	 *
	 * Every PD has a local_dma_lkey which can be used as the lkey value for local
	 * memory operations.
	 */
	struct ib_pd *__ib_alloc_pd(struct ib_device *device, unsigned int flags,
	                const char *caller)

Which doesn't actually work as expected, as kernel-doc will, instead,
document __ib_alloc_pd():

	$ ./scripts/kernel-doc -sphinx-version 3.1 -function ib_alloc_pd drivers/infiniband/core/verbs.c 
	drivers/infiniband/core/verbs.c:1: warning: 'ib_alloc_pd' not found

	$ ./scripts/kernel-doc -sphinx-version 3.1 -function __ib_alloc_pd drivers/infiniband/core/verbs.c 
	.. c:function:: struct ib_pd * __ib_alloc_pd (struct ib_device *device, unsigned int flags, const char *caller)

	   Allocates an unused protection domain.

	**Parameters**

	``struct ib_device *device``
	  The device on which to allocate the protection domain.

	``unsigned int flags``
	  protection domain flags
	
	``const char *caller``
	  caller's build-time module name

	**Description**

	A protection domain object provides an association between QPs, shared
	receive queues, address handles, memory regions, and memory windows.

	Every PD has a local_dma_lkey which can be used as the lkey value for local
	memory operations.

So, what this patch does is to fix the kernel-doc markup at verbs.c for
it to reflect the function that it is documented, adding a new markup for
ib_alloc_pd(), which is identical to __ib_alloc_pd(), except for the
@caller field, which is set to KBUILD_MODNAME by this macro.

Thanks,
Mauro

^ permalink raw reply	[flat|nested] 51+ messages in thread

end of thread, other threads:[~2020-12-01 11:40 UTC | newest]

Thread overview: 51+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-11-16 10:17 [PATCH v4 00/27]Fix several bad kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:17 ` [PATCH v4 01/27] net: phy: fix " Mauro Carvalho Chehab
2020-11-16 10:17 ` [PATCH v4 02/27] net: datagram: fix some " Mauro Carvalho Chehab
2020-11-16 10:20   ` Kirill Tkhai
2020-11-16 10:17 ` [PATCH v4 03/27] net: core: " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 04/27] s390: fix " Mauro Carvalho Chehab
2020-11-16 10:25   ` Cornelia Huck
2020-11-16 10:38   ` Vineeth Vijayan
2020-11-16 12:04     ` Vineeth Vijayan
2020-11-16 10:18 ` [PATCH v4 05/27] drm: fix some " Mauro Carvalho Chehab
2020-11-16 11:37   ` Jani Nikula
2020-11-16 19:48     ` Daniel Vetter
2020-11-16 10:18 ` [PATCH v4 06/27] HSI: fix a kernel-doc markup Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 07/27] IB: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:36   ` Gustavo A. R. Silva
2020-11-23 23:45   ` Jason Gunthorpe
2020-12-01 11:39     ` Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 08/27] parport: fix a kernel-doc markup Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 09/27] rapidio: fix kernel-doc a markup Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 10/27] video: fix some kernel-doc markups Mauro Carvalho Chehab
2020-11-16 15:36   ` Daniel Vetter
2020-11-16 16:38     ` Mauro Carvalho Chehab
2020-11-16 17:24       ` Daniel Vetter
2020-11-16 18:11         ` Sam Ravnborg
2020-11-16 19:43           ` Daniel Vetter
2020-11-16 18:42         ` Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 11/27] fs: fix " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 12/27] jbd2: " Mauro Carvalho Chehab
2020-11-20  3:38   ` Theodore Y. Ts'o
2020-11-16 10:18 ` [PATCH v4 13/27] pstore/zone: fix a kernel-doc markup Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 14/27] completion: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 11:36   ` Peter Zijlstra
2020-11-16 10:18 ` [PATCH v4 15/27] firmware: stratix10-svc: " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 16/27] connector: fix a kernel-doc markup Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 17/27] lib/crc7: " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 18/27] hrtimer: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 19/27] genirq: " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 20/27] list: fix a typo at the kernel-doc markup Mauro Carvalho Chehab
2020-11-16 19:57   ` Paul E. McKenney
2020-11-16 10:18 ` [PATCH v4 21/27] memblock: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 22/27] w1: fix a kernel-doc markup Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 23/27] resource: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 24/27] shed: fix kernel-doc markup Mauro Carvalho Chehab
2020-11-16 12:34   ` Vincent Guittot
2020-11-16 10:18 ` [PATCH v4 25/27] mm: fix kernel-doc markups Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 26/27] selftests: kselftest_harness.h: partially " Mauro Carvalho Chehab
2020-11-16 10:18 ` [PATCH v4 27/27] scripts: kernel-doc: validate kernel-doc markup with the actual names Mauro Carvalho Chehab
2020-11-16 15:06   ` kernel test robot
2020-11-16 15:42   ` kernel test robot
2020-11-16 15:51   ` kernel test robot
2020-11-17 22:19 ` [PATCH v4 00/27]Fix several bad kernel-doc markups Jakub Kicinski

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).