[PATCH v3 00/56] Fix several bad kernel-doc markups

[PATCH v3 00/56] Fix several bad kernel-doc markups

[Mauro Carvalho Chehab]

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

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

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

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

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


The output (in ReST format) will be:

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

	   function foo

	**Parameters**

	``int args``
	  foo args


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

	   function bar

	**Parameters**

	``void *args``
	  foo args

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

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

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

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

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

This series is based on current upstream tree.

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

Jon,

The first patch contains a trivial bug fix that I got
at kernel-doc script while writing this series. Feel
free to pick it anytime.

The last one should likely be applied only after we
have everything else in place, as otherwise it will 
produce hundreds of warnings, and the broken
markups will be ignored.

Mauro Carvalho Chehab (56):
  scripts: kernel-doc: fix typedef parsing
  drm: amdgpu_dm: fix a typo
  amdgpu: fix a few kernel-doc markup issues
  drm: drm_print.h: fix kernel-doc markups
  s390: fix kernel-doc markups
  x86: mtrr: fix a kernel-doc markup
  block: blk-mq: fix a kernel-doc markup
  ata: fix some kernel-doc markups
  drivers: base: fix some kernel-doc markups
  EDAC: fix some kernel-doc markups
  drm/amdgpu: fix some kernel-doc markups
  drm: fix some kernel-doc markups
  HSI: fix a kernel-doc markup
  IB: fix kernel-doc markups
  media: fix kernel-doc markups
  mei: bus: fix a kernel-doc markup
  mtd: rawnand: fix a kernel-doc markup
  net: phy: fix kernel-doc markups
  net: datagram: fix some kernel-doc markups
  net: core: fix some kernel-doc markups
  mac80211: fix kernel-doc markups
  parport: fix a kernel-doc markup
  PCI: fix kernel-doc markups
  PNP: fix kernel-doc markups
  rapidio: fix kernel-doc a markup
  regulator: fix a kernel-doc markup
  scsi: fix some kernel-doc markups
  slimbus: fix a kernel-doc markup
  spi: fix a typo inside a kernel-doc markup
  uio: fix some kernel-doc markups
  usb: dwc3: fix kernel-doc markups
  video: fix some kernel-doc markups
  vme: fix two kernel-doc markups
  fs: fix kernel-doc markups
  jbd2: fix kernel-doc markups
  locks: fix a typo at a kernel-doc markup
  pstore/zone: fix a kernel-doc markup
  clk: 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
  iio: fix a kernel-doc markup
  list: fix a typo at the kernel-doc markup
  memblock: fix kernel-doc markups
  sound: fix kernel-doc markups
  refcount.h: fix a kernel-doc markup
  w1: fix a kernel-doc markup
  audit: 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
  scrpits: kernel-doc: validate kernel-doc markup with the actual names

 arch/s390/include/asm/ccwdev.h                |  2 +-
 arch/s390/include/asm/cio.h                   |  2 +-
 arch/x86/kernel/cpu/mtrr/mtrr.c               |  3 +-
 block/blk-mq.c                                |  2 +-
 drivers/ata/libata-core.c                     |  2 +-
 drivers/ata/libata-eh.c                       |  2 +-
 drivers/ata/libata-scsi.c                     |  2 +-
 drivers/base/class.c                          |  2 +-
 drivers/base/devres.c                         |  2 +-
 drivers/base/firmware_loader/fallback.c       |  2 +-
 drivers/edac/edac_device.h                    | 11 ++-
 drivers/gpu/drm/amd/amdgpu/amdgpu_device.c    |  8 ++-
 drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c        |  2 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c  |  2 +-
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c |  2 +-
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h |  6 +-
 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/media/dvb-frontends/ascot2e.h         |  2 +-
 drivers/media/dvb-frontends/cxd2820r.h        |  2 +-
 drivers/media/dvb-frontends/drxk.h            |  2 +-
 drivers/media/dvb-frontends/dvb-pll.h         |  2 +-
 drivers/media/dvb-frontends/helene.h          |  4 +-
 drivers/media/dvb-frontends/horus3a.h         |  2 +-
 drivers/media/dvb-frontends/ix2505v.h         |  4 +-
 drivers/media/dvb-frontends/m88ds3103.h       |  2 +-
 drivers/media/dvb-frontends/mb86a20s.h        |  2 +-
 drivers/media/dvb-frontends/stb6000.h         |  2 +-
 drivers/media/dvb-frontends/tda826x.h         |  2 +-
 drivers/media/dvb-frontends/zl10036.h         |  4 +-
 drivers/misc/mei/bus.c                        |  2 +-
 drivers/mtd/nand/raw/nand_bbt.c               |  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/pci/p2pdma.c                          | 10 +--
 drivers/pci/pci-driver.c                      |  4 +-
 drivers/pci/pci.c                             |  2 +-
 drivers/pci/probe.c                           |  4 +-
 drivers/pci/slot.c                            |  5 +-
 drivers/pnp/core.c                            |  4 +-
 drivers/rapidio/rio.c                         |  2 +-
 drivers/regulator/core.c                      |  2 +-
 drivers/scsi/iscsi_tcp.c                      |  4 +-
 drivers/scsi/libiscsi.c                       |  2 +-
 drivers/scsi/scsi_devinfo.c                   |  3 +-
 drivers/scsi/scsi_lib.c                       |  6 +-
 drivers/scsi/scsi_transport_fc.c              |  2 +-
 drivers/slimbus/slimbus.h                     |  2 +-
 drivers/spi/spi.c                             |  6 +-
 .../staging/media/ipu3/include/intel-ipu3.h   |  8 +--
 drivers/uio/uio.c                             |  4 +-
 drivers/usb/dwc3/core.c                       |  2 +-
 drivers/usb/dwc3/core.h                       |  2 +-
 drivers/usb/gadget/composite.c                |  2 +-
 drivers/usb/typec/mux.c                       |  2 +-
 drivers/video/fbdev/core/fbcmap.c             |  2 +-
 drivers/video/hdmi.c                          |  3 +-
 drivers/vme/vme.c                             |  4 +-
 fs/dcache.c                                   | 72 +++++++++----------
 fs/inode.c                                    |  4 +-
 fs/jbd2/journal.c                             | 34 ++++-----
 fs/jbd2/transaction.c                         | 31 ++++----
 fs/locks.c                                    |  2 +-
 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/drm/drm_print.h                       | 20 +++++-
 include/linux/clk.h                           |  2 +-
 include/linux/completion.h                    | 10 ++-
 include/linux/connector.h                     |  2 +-
 include/linux/device/class.h                  | 14 ++++
 include/linux/edac.h                          |  4 +-
 .../firmware/intel/stratix10-svc-client.h     | 10 +--
 include/linux/hrtimer.h                       |  6 +-
 include/linux/iio/trigger.h                   |  2 +-
 include/linux/jbd2.h                          |  2 +-
 include/linux/list.h                          |  2 +-
 include/linux/memblock.h                      |  4 +-
 include/linux/mtd/rawnand.h                   |  3 +-
 include/linux/netdevice.h                     | 11 ++-
 include/linux/parport.h                       | 31 ++++++++
 include/linux/refcount.h                      |  2 +-
 include/linux/uio_driver.h                    | 16 +++++
 include/linux/usb/composite.h                 |  2 +-
 include/linux/w1.h                            |  2 +-
 include/media/dvbdev.h                        |  2 +-
 include/media/v4l2-ctrls.h                    |  2 +-
 include/media/v4l2-dev.h                      |  4 +-
 include/media/v4l2-device.h                   |  2 +-
 include/media/v4l2-dv-timings.h               |  2 +-
 include/media/v4l2-fwnode.h                   |  2 +-
 include/media/v4l2-mediabus.h                 |  6 +-
 include/media/v4l2-subdev.h                   |  2 +-
 include/media/videobuf2-core.h                |  2 +-
 include/net/cfg80211.h                        |  9 +--
 include/net/mac80211.h                        |  7 +-
 include/rdma/ib_verbs.h                       | 11 +++
 include/sound/core.h                          |  3 +-
 include/sound/pcm.h                           |  4 +-
 include/uapi/drm/amdgpu_drm.h                 |  2 +-
 include/uapi/sound/compress_offload.h         |  2 +-
 kernel/audit.c                                |  2 +-
 kernel/irq/chip.c                             |  2 +-
 kernel/irq/generic-chip.c                     |  2 +-
 kernel/resource.c                             | 24 ++++---
 kernel/sched/core.c                           | 16 ++---
 kernel/sched/fair.c                           |  3 +-
 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/mac80211/sta_info.h                       |  9 ++-
 net/sunrpc/rpc_pipe.c                         |  3 +-
 scripts/kernel-doc                            | 64 ++++++++++++-----
 sound/core/control.c                          |  4 +-
 sound/core/pcm_dmaengine.c                    |  3 +-
 sound/core/pcm_lib.c                          |  2 +-
 sound/core/pcm_native.c                       |  4 +-
 sound/soc/soc-core.c                          |  2 +-
 sound/soc/soc-dapm.c                          |  2 +-
 tools/testing/selftests/kselftest_harness.h   | 66 ++++++++---------
 161 files changed, 558 insertions(+), 382 deletions(-)

-- 
2.26.2

[PATCH v3 01/56] scripts: kernel-doc: fix typedef parsing

[Mauro Carvalho Chehab]

The include/linux/genalloc.h file defined this typedef:

	typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);

Because it has a type composite of two words (unsigned long),
the parser gets the typedef name wrong:

.. c:macro:: long

   **Typedef**: Allocation callback function type definition

Fix the regex in order to accept composite types when
defining a typedef for a function pointer.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99cd8418ff8a..311d213ee74d 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1438,7 +1438,7 @@ sub dump_typedef($$) {
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
 
     # Parse function prototypes
-    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
+    if ($x =~ /typedef\s+(\w+\s*){1,}\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
 	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
 
 	# Function typedefs
-- 
2.26.2

[PATCH v3 02/56] drm: amdgpu_dm: fix a typo

[Mauro Carvalho Chehab]

	dm_comressor_info -> dm_compressor_info

The kernel-doc markup is right, but the struct itself
and their references contain a typo.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c | 2 +-
 drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
index bb1bc7f5d149..48ec0535d92f 100644
--- a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
+++ b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
@@ -583,7 +583,7 @@ static void amdgpu_dm_fbc_init(struct drm_connector *connector)
 {
 	struct drm_device *dev = connector->dev;
 	struct amdgpu_device *adev = drm_to_adev(dev);
-	struct dm_comressor_info *compressor = &adev->dm.compressor;
+	struct dm_compressor_info *compressor = &adev->dm.compressor;
 	struct amdgpu_dm_connector *aconn = to_amdgpu_dm_connector(connector);
 	struct drm_display_mode *mode;
 	unsigned long max_size = 0;
diff --git a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
index 34f6369bf51f..a8a0e8cb1a11 100644
--- a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
+++ b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
@@ -86,7 +86,7 @@ struct irq_list_head {
  * @bo_ptr: Pointer to the buffer object
  * @gpu_addr: MMIO gpu addr
  */
-struct dm_comressor_info {
+struct dm_compressor_info {
 	void *cpu_addr;
 	struct amdgpu_bo *bo_ptr;
 	uint64_t gpu_addr;
@@ -148,7 +148,7 @@ struct amdgpu_dm_backlight_caps {
  * @soc_bounding_box: SOC bounding box values provided by gpu_info FW
  * @cached_state: Caches device atomic state for suspend/resume
  * @cached_dc_state: Cached state of content streams
- * @compressor: Frame buffer compression buffer. See &struct dm_comressor_info
+ * @compressor: Frame buffer compression buffer. See &struct dm_compressor_info
  * @force_timing_sync: set via debugfs. When set, indicates that all connected
  *		       displays will be forced to synchronize.
  */
@@ -324,7 +324,7 @@ struct amdgpu_display_manager {
 	struct drm_atomic_state *cached_state;
 	struct dc_state *cached_dc_state;
 
-	struct dm_comressor_info compressor;
+	struct dm_compressor_info compressor;
 
 	const struct firmware *fw_dmcu;
 	uint32_t dmcu_fw_version;
-- 
2.26.2

[PATCH v3 03/56] amdgpu: fix a few kernel-doc markup issues

[Mauro Carvalho Chehab]

A kernel-doc markup can't be mixed with a random comment,
as it causes parsing problems.

While here, change an invalid kernel-doc markup into
a common comment.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/amd/amdgpu/amdgpu_device.c | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
index f8785bdec79c..1d4b54950528 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
@@ -239,9 +239,11 @@ bool amdgpu_device_supports_baco(struct drm_device *dev)
 	return amdgpu_asic_supports_baco(adev);
 }
 
+/*
+ * VRAM access helper functions
+ */
+
 /**
- * VRAM access helper functions.
- *
  * amdgpu_device_vram_access - read/write a buffer in vram
  *
  * @adev: amdgpu_device pointer
@@ -4497,7 +4499,7 @@ int amdgpu_device_gpu_recover(struct amdgpu_device *adev,
 	bool need_emergency_restart = false;
 	bool audio_suspended = false;
 
-	/**
+	/*
 	 * Special case: RAS triggered and full reset isn't supported
 	 */
 	need_emergency_restart = amdgpu_ras_need_emergency_restart(adev);
-- 
2.26.2

[PATCH v3 04/56] drm: drm_print.h: fix kernel-doc markups

[Mauro Carvalho Chehab]

A kernel-doc markup should start with the identifier on its
first line.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/drm/drm_print.h | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/include/drm/drm_print.h b/include/drm/drm_print.h
index 1c9417430d08..f32d179e139d 100644
--- a/include/drm/drm_print.h
+++ b/include/drm/drm_print.h
@@ -338,7 +338,7 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category,
 		 const char *format, ...);
 
 /**
- * Error output.
+ * DRM_DEV_ERROR() - Error output.
  *
  * @dev: device pointer
  * @fmt: printf() like format string.
@@ -347,10 +347,12 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category,
 	drm_dev_printk(dev, KERN_ERR, "*ERROR* " fmt, ##__VA_ARGS__)
 
 /**
- * Rate limited error output.  Like DRM_ERROR() but won't flood the log.
+ * DRM_DEV_ERROR_RATELIMITED() - Rate limited error output.
  *
  * @dev: device pointer
  * @fmt: printf() like format string.
+ *
+ * Like DRM_ERROR() but won't flood the log.
  */
 #define DRM_DEV_ERROR_RATELIMITED(dev, fmt, ...)			\
 ({									\
@@ -375,15 +377,27 @@ void drm_dev_dbg(const struct device *dev, enum drm_debug_category category,
 })
 
 /**
- * Debug output.
+ * DRM_DEV_DEBUG() - Debug output for generic drm code
  *
  * @dev: device pointer
  * @fmt: printf() like format string.
  */
 #define DRM_DEV_DEBUG(dev, fmt, ...)					\
 	drm_dev_dbg(dev, DRM_UT_CORE, fmt, ##__VA_ARGS__)
+/**
+ * DRM_DEV_DEBUG_DRIVER() - Debug output for vendor specific part of the driver
+ *
+ * @dev: device pointer
+ * @fmt: printf() like format string.
+ */
 #define DRM_DEV_DEBUG_DRIVER(dev, fmt, ...)				\
 	drm_dev_dbg(dev, DRM_UT_DRIVER,	fmt, ##__VA_ARGS__)
+/**
+ * DRM_DEV_DEBUG_KMS() - Debug output for modesetting code
+ *
+ * @dev: device pointer
+ * @fmt: printf() like format string.
+ */
 #define DRM_DEV_DEBUG_KMS(dev, fmt, ...)				\
 	drm_dev_dbg(dev, DRM_UT_KMS, fmt, ##__VA_ARGS__)
 
-- 
2.26.2

[PATCH v3 05/56] s390: fix kernel-doc markups

[Mauro Carvalho Chehab]

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 c0be5fe1ddba..069709b8e9e7 100644
--- a/arch/s390/include/asm/ccwdev.h
+++ b/arch/s390/include/asm/ccwdev.h
@@ -115,7 +115,7 @@ enum uc_todo {
 };
 
 /**
- * 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
diff --git a/arch/s390/include/asm/cio.h b/arch/s390/include/asm/cio.h
index 5c58756d6476..23dceb8d0453 100644
--- a/arch/s390/include/asm/cio.h
+++ b/arch/s390/include/asm/cio.h
@@ -329,7 +329,7 @@ struct ccw_dev_id {
 };
 
 /**
- * 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:
-- 
2.26.2

[PATCH v3 06/56] x86: mtrr: fix a kernel-doc markup

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 arch/x86/kernel/cpu/mtrr/mtrr.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/arch/x86/kernel/cpu/mtrr/mtrr.c b/arch/x86/kernel/cpu/mtrr/mtrr.c
index 6a80f36b5d59..08a30c8e9431 100644
--- a/arch/x86/kernel/cpu/mtrr/mtrr.c
+++ b/arch/x86/kernel/cpu/mtrr/mtrr.c
@@ -813,7 +813,8 @@ void mtrr_ap_init(void)
 }
 
 /**
- * Save current fixed-range MTRR state of the first cpu in cpu_online_mask.
+ * mtrr_save_state - Save current fixed-range MTRR state of the first
+ *	cpu in cpu_online_mask.
  */
 void mtrr_save_state(void)
 {
-- 
2.26.2

[PATCH v3 07/56] block: blk-mq: fix a kernel-doc markup

[Mauro Carvalho Chehab]

Fix a typo:
	blk_mq_run_hw_queue -> blk_mq_run_hw_queues

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

diff --git a/block/blk-mq.c b/block/blk-mq.c
index 696450257ac1..bca2e3962262 100644
--- a/block/blk-mq.c
+++ b/block/blk-mq.c
@@ -1664,7 +1664,7 @@ void blk_mq_run_hw_queue(struct blk_mq_hw_ctx *hctx, bool async)
 EXPORT_SYMBOL(blk_mq_run_hw_queue);
 
 /**
- * blk_mq_run_hw_queue - Run all hardware queues in a request queue.
+ * blk_mq_run_hw_queues - Run all hardware queues in a request queue.
  * @q: Pointer to the request queue to run.
  * @async: If we want to run the queue asynchronously.
  */
-- 
2.26.2

[PATCH v3 08/56] ata: fix some kernel-doc markups

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/ata/libata-core.c | 2 +-
 drivers/ata/libata-eh.c   | 2 +-
 drivers/ata/libata-scsi.c | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/ata/libata-core.c b/drivers/ata/libata-core.c
index f546a5761c4f..61c762961ca8 100644
--- a/drivers/ata/libata-core.c
+++ b/drivers/ata/libata-core.c
@@ -5616,7 +5616,7 @@ int ata_host_start(struct ata_host *host)
 EXPORT_SYMBOL_GPL(ata_host_start);
 
 /**
- *	ata_sas_host_init - Initialize a host struct for sas (ipr, libsas)
+ *	ata_host_init - Initialize a host struct for sas (ipr, libsas)
  *	@host:	host to initialize
  *	@dev:	device host is attached to
  *	@ops:	port_ops
diff --git a/drivers/ata/libata-eh.c b/drivers/ata/libata-eh.c
index d912eaa65c94..b6f92050e60c 100644
--- a/drivers/ata/libata-eh.c
+++ b/drivers/ata/libata-eh.c
@@ -1115,7 +1115,7 @@ void ata_eh_freeze_port(struct ata_port *ap)
 EXPORT_SYMBOL_GPL(ata_eh_freeze_port);
 
 /**
- *	ata_port_thaw_port - EH helper to thaw port
+ *	ata_eh_thaw_port - EH helper to thaw port
  *	@ap: ATA port to thaw
  *
  *	Thaw frozen port @ap.
diff --git a/drivers/ata/libata-scsi.c b/drivers/ata/libata-scsi.c
index 70431912dc63..48b8934970f3 100644
--- a/drivers/ata/libata-scsi.c
+++ b/drivers/ata/libata-scsi.c
@@ -1003,7 +1003,7 @@ void ata_scsi_sdev_config(struct scsi_device *sdev)
 }
 
 /**
- *	atapi_drain_needed - Check whether data transfer may overflow
+ *	ata_scsi_dma_need_drain - Check whether data transfer may overflow
  *	@rq: request to be checked
  *
  *	ATAPI commands which transfer variable length data to host
-- 
2.26.2

[PATCH v3 09/56] drivers: base: fix some kernel-doc markups

[Mauro Carvalho Chehab]

class_create is actually defined at the header. Fix the
markup there and add a new one at the right place.

While here, also fix some markups for functions that have
different names between their prototypes and kernel-doc
comments.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/base/class.c                    |  2 +-
 drivers/base/devres.c                   |  2 +-
 drivers/base/firmware_loader/fallback.c |  2 +-
 include/linux/device/class.h            | 14 ++++++++++++++
 4 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/drivers/base/class.c b/drivers/base/class.c
index c3451481194e..7476f393df97 100644
--- a/drivers/base/class.c
+++ b/drivers/base/class.c
@@ -210,7 +210,7 @@ static void class_create_release(struct class *cls)
 }
 
 /**
- * class_create - create a struct class structure
+ * __class_create - create a struct class structure
  * @owner: pointer to the module that is to "own" this struct class
  * @name: pointer to a string for the name of this class.
  * @key: the lock_class_key for this class; used by mutex lock debugging
diff --git a/drivers/base/devres.c b/drivers/base/devres.c
index 586e9a75c840..fb9d5289a620 100644
--- a/drivers/base/devres.c
+++ b/drivers/base/devres.c
@@ -149,7 +149,7 @@ void * __devres_alloc_node(dr_release_t release, size_t size, gfp_t gfp, int nid
 EXPORT_SYMBOL_GPL(__devres_alloc_node);
 #else
 /**
- * devres_alloc - Allocate device resource data
+ * devres_alloc_node - Allocate device resource data
  * @release: Release function devres will be associated with
  * @size: Allocation size
  * @gfp: Allocation flags
diff --git a/drivers/base/firmware_loader/fallback.c b/drivers/base/firmware_loader/fallback.c
index 4dec4b79ae06..91899d185e31 100644
--- a/drivers/base/firmware_loader/fallback.c
+++ b/drivers/base/firmware_loader/fallback.c
@@ -128,7 +128,7 @@ static ssize_t timeout_show(struct class *class, struct class_attribute *attr,
 }
 
 /**
- * firmware_timeout_store() - set number of seconds to wait for firmware
+ * timeout_store() - set number of seconds to wait for firmware
  * @class: device class pointer
  * @attr: device attribute pointer
  * @buf: buffer to scan for timeout value
diff --git a/include/linux/device/class.h b/include/linux/device/class.h
index e8d470c457d1..e61ec5502019 100644
--- a/include/linux/device/class.h
+++ b/include/linux/device/class.h
@@ -256,6 +256,20 @@ extern void class_destroy(struct class *cls);
 
 /* This is a #define to keep the compiler from merging different
  * instances of the __key variable */
+
+/**
+ * class_create - create a struct class structure
+ * @owner: pointer to the module that is to "own" this struct class
+ * @name: pointer to a string for the name of this class.
+ *
+ * This is used to create a struct class pointer that can then be used
+ * in calls to device_create().
+ *
+ * Returns &struct class pointer on success, or ERR_PTR() on error.
+ *
+ * Note, the pointer created here is to be destroyed when finished by
+ * making a call to class_destroy().
+ */
 #define class_create(owner, name)		\
 ({						\
 	static struct lock_class_key __key;	\
-- 
2.26.2

[PATCH v3 10/56] EDAC: fix some kernel-doc markups

[Mauro Carvalho Chehab]

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

Also, some enums are using wrong names at the kernel-doc
markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/edac/edac_device.h | 11 +++++------
 include/linux/edac.h       |  4 ++--
 2 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/drivers/edac/edac_device.h b/drivers/edac/edac_device.h
index c4c0e0bdce14..f90cbbb2ff73 100644
--- a/drivers/edac/edac_device.h
+++ b/drivers/edac/edac_device.h
@@ -258,7 +258,7 @@ extern struct edac_device_ctl_info *edac_device_alloc_ctl_info(
 extern void edac_device_free_ctl_info(struct edac_device_ctl_info *ctl_info);
 
 /**
- * edac_device_add_device: Insert the 'edac_dev' structure into the
+ * edac_device_add_device - Insert the 'edac_dev' structure into the
  *	 edac_device global list and create sysfs entries associated with
  *	 edac_device structure.
  *
@@ -271,9 +271,8 @@ extern void edac_device_free_ctl_info(struct edac_device_ctl_info *ctl_info);
 extern int edac_device_add_device(struct edac_device_ctl_info *edac_dev);
 
 /**
- * edac_device_del_device:
- *	Remove sysfs entries for specified edac_device structure and
- *	then remove edac_device structure from global list
+ * edac_device_del_device - Remove sysfs entries for specified edac_device
+ * 	structure and then remove edac_device structure from global list
  *
  * @dev:
  *	Pointer to struct &device representing the edac device
@@ -286,7 +285,7 @@ extern int edac_device_add_device(struct edac_device_ctl_info *edac_dev);
 extern struct edac_device_ctl_info *edac_device_del_device(struct device *dev);
 
 /**
- * Log correctable errors.
+ * edac_device_handle_ce_count - Log correctable errors.
  *
  * @edac_dev: pointer to struct &edac_device_ctl_info
  * @inst_nr: number of the instance where the CE error happened
@@ -299,7 +298,7 @@ void edac_device_handle_ce_count(struct edac_device_ctl_info *edac_dev,
 				 const char *msg);
 
 /**
- * Log uncorrectable errors.
+ * edac_device_handle_ue_count - Log uncorrectable errors.
  *
  * @edac_dev: pointer to struct &edac_device_ctl_info
  * @inst_nr: number of the instance where the CE error happened
diff --git a/include/linux/edac.h b/include/linux/edac.h
index 15e8f3d8a895..52d7487f6bd4 100644
--- a/include/linux/edac.h
+++ b/include/linux/edac.h
@@ -229,7 +229,7 @@ enum mem_type {
 #define MEM_FLAG_NVDIMM         BIT(MEM_NVDIMM)
 
 /**
- * enum edac-type - Error Detection and Correction capabilities and mode
+ * enum edac_type - Error Detection and Correction capabilities and mode
  * @EDAC_UNKNOWN:	Unknown if ECC is available
  * @EDAC_NONE:		Doesn't support ECC
  * @EDAC_RESERVED:	Reserved ECC type
@@ -309,7 +309,7 @@ enum scrub_type {
 #define OP_OFFLINE		0x300
 
 /**
- * enum edac_mc_layer - memory controller hierarchy layer
+ * enum edac_mc_layer_type - memory controller hierarchy layer
  *
  * @EDAC_MC_LAYER_BRANCH:	memory layer is named "branch"
  * @EDAC_MC_LAYER_CHANNEL:	memory layer is named "channel"
-- 
2.26.2

[PATCH v3 11/56] drm/amdgpu: fix some kernel-doc markups

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c       | 2 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 2 +-
 include/uapi/drm/amdgpu_drm.h                | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
index df110afa97bf..a5f73a267fe5 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
@@ -2166,7 +2166,7 @@ struct amdgpu_bo_va *amdgpu_vm_bo_add(struct amdgpu_device *adev,
 
 
 /**
- * amdgpu_vm_bo_insert_mapping - insert a new mapping
+ * amdgpu_vm_bo_insert_map - insert a new mapping
  *
  * @adev: amdgpu_device pointer
  * @bo_va: bo_va to store the address
diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
index 0c6b7c5ecfec..795bad307497 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
@@ -528,7 +528,7 @@ int amdgpu_vram_mgr_alloc_sgt(struct amdgpu_device *adev,
 }
 
 /**
- * amdgpu_vram_mgr_alloc_sgt - allocate and fill a sg table
+ * amdgpu_vram_mgr_free_sgt - allocate and fill a sg table
  *
  * @adev: amdgpu device pointer
  * @sgt: sg table to free
diff --git a/include/uapi/drm/amdgpu_drm.h b/include/uapi/drm/amdgpu_drm.h
index c5ff2b275fcd..791a1d597d2a 100644
--- a/include/uapi/drm/amdgpu_drm.h
+++ b/include/uapi/drm/amdgpu_drm.h
@@ -667,7 +667,7 @@ struct drm_amdgpu_cs_chunk_data {
 	};
 };
 
-/**
+/*
  *  Query h/w info: Flag that this is integrated (a.h.a. fusion) GPU
  *
  */
-- 
2.26.2

[PATCH v3 12/56] drm: fix some kernel-doc markups

[Mauro Carvalho Chehab]

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
@@ -543,7 +543,7 @@ void drm_atomic_helper_connector_destroy_state(struct drm_connector *connector,
 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
  *
diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
index 717c4e7271b0..9dde11466cc2 100644
--- a/drivers/gpu/drm/drm_connector.c
+++ b/drivers/gpu/drm/drm_connector.c
@@ -1427,7 +1427,8 @@ void drm_hdmi_avi_infoframe_content_type(struct hdmi_avi_infoframe *frame,
 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.
diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
index deeed73f4ed6..485c3e78ba98 100644
--- a/drivers/gpu/drm/drm_dp_helper.c
+++ b/drivers/gpu/drm/drm_dp_helper.c
@@ -1084,7 +1084,7 @@ drm_dp_subconnector_type(const u8 dpcd[DP_RECEIVER_CAP_SIZE],
 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
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
@@ -552,7 +552,7 @@ int drm_mode_getfb(struct drm_device *dev,
 }
 
 /**
- * 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
diff --git a/drivers/gpu/drm/drm_gem.c b/drivers/gpu/drm/drm_gem.c
index 19d73868490e..74af32106cae 100644
--- a/drivers/gpu/drm/drm_gem.c
+++ b/drivers/gpu/drm/drm_gem.c
@@ -873,7 +873,7 @@ drm_gem_flink_ioctl(struct drm_device *dev, void *data,
 }
 
 /**
- * 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
@@ -918,7 +918,7 @@ drm_gem_open_ioctl(struct drm_device *dev, void *data,
 }
 
 /**
- * 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
  *
diff --git a/drivers/gpu/drm/drm_gem_vram_helper.c b/drivers/gpu/drm/drm_gem_vram_helper.c
index 50cad0e4a92e..e81f6954d233 100644
--- a/drivers/gpu/drm/drm_gem_vram_helper.c
+++ b/drivers/gpu/drm/drm_gem_vram_helper.c
@@ -640,7 +640,7 @@ static void drm_gem_vram_object_free(struct drm_gem_object *gem)
  */
 
 /**
- * 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
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
@@ -115,7 +115,7 @@ void drm_mode_object_unregister(struct drm_device *dev,
 }
 
 /**
- * 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
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
@@ -1889,7 +1889,7 @@ drm_mode_create_from_cmdline_mode(struct drm_device *dev,
 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
  *
@@ -1941,7 +1941,7 @@ void drm_mode_convert_to_umode(struct drm_mode_modeinfo *out,
 }
 
 /**
- * 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
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
@@ -125,7 +125,7 @@ ssize_t drm_scdc_write(struct i2c_adapter *adapter, u8 offset,
 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
diff --git a/drivers/gpu/drm/i915/display/intel_dpll_mgr.c b/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
index e08684e34078..8abbae8f8808 100644
--- a/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
+++ b/drivers/gpu/drm/i915/display/intel_dpll_mgr.c
@@ -4531,7 +4531,7 @@ void intel_dpll_sanitize_state(struct drm_i915_private *i915)
 }
 
 /**
- * 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
  *
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
@@ -238,7 +238,7 @@ i915_gem_evict_something(struct i915_address_space *vm,
 }
 
 /**
- * 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
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
@@ -625,7 +625,8 @@ static int append_oa_sample(struct i915_perf_stream *stream,
 }
 
 /**
- * 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
@@ -917,7 +918,8 @@ static int gen8_oa_read(struct i915_perf_stream *stream,
 }
 
 /**
- * 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
@@ -3227,7 +3229,7 @@ static long i915_perf_config_locked(struct i915_perf_stream *stream,
 }
 
 /**
- * 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
diff --git a/drivers/gpu/drm/scheduler/sched_main.c b/drivers/gpu/drm/scheduler/sched_main.c
index 9a0d77a68018..c6332d75025e 100644
--- a/drivers/gpu/drm/scheduler/sched_main.c
+++ b/drivers/gpu/drm/scheduler/sched_main.c
@@ -446,7 +446,7 @@ void drm_sched_stop(struct drm_gpu_scheduler *sched, struct drm_sched_job *bad)
 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
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
@@ -64,7 +64,7 @@ v3d_job_free(struct drm_sched_job *sched_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.
diff --git a/drivers/gpu/drm/vc4/vc4_bo.c b/drivers/gpu/drm/vc4/vc4_bo.c
index 74ceebd62fbc..b8c04c6eb7f9 100644
--- a/drivers/gpu/drm/vc4/vc4_bo.c
+++ b/drivers/gpu/drm/vc4/vc4_bo.c
@@ -375,7 +375,7 @@ static struct vc4_bo *vc4_bo_get_from_cache(struct drm_device *dev,
 }
 
 /**
- * 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
  *
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
@@ -167,7 +167,7 @@ int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *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
  *
@@ -180,7 +180,7 @@ int drm_atomic_helper_legacy_gamma_set(struct drm_crtc *crtc,
 	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
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
@@ -84,7 +84,7 @@ enum drm_connector_status {
 };
 
 /**
- * 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
diff --git a/include/drm/drm_device.h b/include/drm/drm_device.h
index f4f68e7a9149..3ae248938305 100644
--- a/include/drm/drm_device.h
+++ b/include/drm/drm_device.h
@@ -27,7 +27,7 @@ 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 {
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
@@ -273,7 +273,8 @@ struct drm_dsc_config {
 };
 
 /**
- * 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.
diff --git a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h
index 62cc6e6c3a4f..9a67dcca1f4a 100644
--- a/include/drm/drm_gem_vram_helper.h
+++ b/include/drm/drm_gem_vram_helper.h
@@ -69,8 +69,8 @@ struct drm_gem_vram_object {
 };
 
 /**
- * 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
  */
@@ -81,8 +81,8 @@ static inline struct drm_gem_vram_object *drm_gem_vram_of_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
  */
-- 
2.26.2

[PATCH v3 13/56] HSI: fix a kernel-doc markup

[Mauro Carvalho Chehab]

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
@@ -352,7 +352,7 @@ static void hsi_port_release(struct device *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)
-- 
2.26.2

[PATCH v3 14/56] IB: fix kernel-doc markups

[Mauro Carvalho Chehab]

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 5740d1ba3568..2dfbfdd6cc57 100644
--- a/drivers/infiniband/core/cm.c
+++ b/drivers/infiniband/core/cm.c
@@ -1251,7 +1251,8 @@ int ib_cm_listen(struct ib_cm_id *cm_id, __be64 service_id, __be64 service_mask)
 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.
@@ -1764,7 +1765,7 @@ static u16 cm_get_bth_pkey(struct cm_work *work)
 }
 
 /**
- * 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.
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
@@ -123,7 +123,7 @@ static int __ib_process_cq(struct ib_cq *cq, int budget, struct ib_wc *wcs,
 }
 
 /**
- * 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
  *
@@ -197,7 +197,7 @@ static void ib_cq_completion_workqueue(struct ib_cq *cq, void *private)
 }
 
 /**
- * __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
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
@@ -141,7 +141,7 @@ int iwpm_wait_complete_req(struct iwpm_nlmsg_request *nlmsg_request);
 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
  */
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
@@ -1435,7 +1435,8 @@ enum opa_pr_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
diff --git a/drivers/infiniband/core/verbs.c b/drivers/infiniband/core/verbs.c
index 740f8454b6b4..89f379cd7909 100644
--- a/drivers/infiniband/core/verbs.c
+++ b/drivers/infiniband/core/verbs.c
@@ -244,7 +244,7 @@ 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
@@ -1662,7 +1662,7 @@ static bool is_qp_type_connected(const struct ib_qp *qp)
 		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,
diff --git a/drivers/infiniband/sw/rdmavt/ah.c b/drivers/infiniband/sw/rdmavt/ah.c
index b938c4ffa99a..3c175bd4ad55 100644
--- a/drivers/infiniband/sw/rdmavt/ah.c
+++ b/drivers/infiniband/sw/rdmavt/ah.c
@@ -126,7 +126,7 @@ int rvt_create_ah(struct ib_ah *ibah, struct rdma_ah_init_attr *init_attr,
 }
 
 /**
- * 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)
  *
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
@@ -54,7 +54,7 @@
 #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
@@ -69,7 +69,7 @@ void rvt_driver_mcast_init(struct rvt_dev_info *rdi)
 }
 
 /**
- * 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)
@@ -98,7 +98,7 @@ static void rvt_mcast_qp_free(struct rvt_mcast_qp *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)
  *
@@ -181,7 +181,7 @@ struct rvt_mcast *rvt_mcast_find(struct rvt_ibport *ibp, union ib_gid *mgid,
 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
  *
@@ -426,8 +426,8 @@ int rvt_detach_mcast(struct ib_qp *ibqp, union ib_gid *gid, u16 lid)
 }
 
 /**
- *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
  */
diff --git a/drivers/infiniband/sw/rdmavt/qp.c b/drivers/infiniband/sw/rdmavt/qp.c
index ee48befc8978..a0cdde8a2335 100644
--- a/drivers/infiniband/sw/rdmavt/qp.c
+++ b/drivers/infiniband/sw/rdmavt/qp.c
@@ -1823,7 +1823,7 @@ int rvt_query_qp(struct ib_qp *ibqp, struct ib_qp_attr *attr,
 }
 
 /**
- * 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
@@ -2245,7 +2245,7 @@ int rvt_post_send(struct ib_qp *ibqp, const struct ib_send_wr *wr,
 }
 
 /**
- * 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
@@ -2497,7 +2497,7 @@ int rvt_get_rwqe(struct rvt_qp *qp, bool wr_id_only)
 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)
@@ -2943,7 +2943,7 @@ static enum ib_wc_status loopback_qp_drop(struct rvt_ibport *rvp,
 }
 
 /**
- * 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
diff --git a/drivers/infiniband/ulp/iser/iscsi_iser.c b/drivers/infiniband/ulp/iser/iscsi_iser.c
index 3690e28cc7ea..84cebf937680 100644
--- a/drivers/infiniband/ulp/iser/iscsi_iser.c
+++ b/drivers/infiniband/ulp/iser/iscsi_iser.c
@@ -739,7 +739,7 @@ iscsi_iser_set_param(struct iscsi_cls_conn *cls_conn,
 }
 
 /**
- * iscsi_iser_set_param() - set class connection parameter
+ * iscsi_iser_conn_get_stats() - set class connection parameter
  * @cls_conn:    iscsi class connection
  * @stats:       iscsi stats to output
  *
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
@@ -437,7 +437,7 @@ struct opa_veswport_trap {
 } __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 {
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
@@ -74,7 +74,7 @@ void opa_vnic_vema_report_event(struct opa_vnic_adapter *adapter, u8 event)
 }
 
 /**
- * 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
  *
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
@@ -347,7 +347,7 @@ struct srpt_nexus {
 };
 
 /**
- * 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.
diff --git a/include/rdma/ib_verbs.h b/include/rdma/ib_verbs.h
index 9bf6c319a670..5837bf0ac451 100644
--- a/include/rdma/ib_verbs.h
+++ b/include/rdma/ib_verbs.h
@@ -3430,6 +3430,17 @@ enum ib_pd_flags {
 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)
 
-- 
2.26.2

[PATCH v3 15/56] media: fix kernel-doc markups

[Mauro Carvalho Chehab]

Some identifiers have different names between their prototypes
and the kernel-doc markup. Seome seems to be due to cut-and-paste
related issues.

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/media/dvb-frontends/ascot2e.h           | 2 +-
 drivers/media/dvb-frontends/cxd2820r.h          | 2 +-
 drivers/media/dvb-frontends/drxk.h              | 2 +-
 drivers/media/dvb-frontends/dvb-pll.h           | 2 +-
 drivers/media/dvb-frontends/helene.h            | 4 ++--
 drivers/media/dvb-frontends/horus3a.h           | 2 +-
 drivers/media/dvb-frontends/ix2505v.h           | 4 ++--
 drivers/media/dvb-frontends/m88ds3103.h         | 2 +-
 drivers/media/dvb-frontends/mb86a20s.h          | 2 +-
 drivers/media/dvb-frontends/stb6000.h           | 2 +-
 drivers/media/dvb-frontends/tda826x.h           | 2 +-
 drivers/media/dvb-frontends/zl10036.h           | 4 ++--
 drivers/staging/media/ipu3/include/intel-ipu3.h | 8 ++++----
 include/media/dvbdev.h                          | 2 +-
 include/media/v4l2-ctrls.h                      | 2 +-
 include/media/v4l2-dev.h                        | 4 ++--
 include/media/v4l2-device.h                     | 2 +-
 include/media/v4l2-dv-timings.h                 | 2 +-
 include/media/v4l2-fwnode.h                     | 2 +-
 include/media/v4l2-mediabus.h                   | 6 +++---
 include/media/v4l2-subdev.h                     | 2 +-
 include/media/videobuf2-core.h                  | 2 +-
 22 files changed, 31 insertions(+), 31 deletions(-)

diff --git a/drivers/media/dvb-frontends/ascot2e.h b/drivers/media/dvb-frontends/ascot2e.h
index f886fab1283f..d86b3de85c6a 100644
--- a/drivers/media/dvb-frontends/ascot2e.h
+++ b/drivers/media/dvb-frontends/ascot2e.h
@@ -33,7 +33,7 @@ struct ascot2e_config {
 
 #if IS_REACHABLE(CONFIG_DVB_ASCOT2E)
 /**
- * Attach an ascot2e tuner
+ * ascot2e_attach - Attach an ascot2e tuner
  *
  * @fe: frontend to be attached
  * @config: pointer to &struct ascot2e_config with tuner configuration.
diff --git a/drivers/media/dvb-frontends/cxd2820r.h b/drivers/media/dvb-frontends/cxd2820r.h
index a28b8754932b..4aa6cf4fb913 100644
--- a/drivers/media/dvb-frontends/cxd2820r.h
+++ b/drivers/media/dvb-frontends/cxd2820r.h
@@ -96,7 +96,7 @@ struct cxd2820r_config {
 
 #if IS_REACHABLE(CONFIG_DVB_CXD2820R)
 /**
- * Attach a cxd2820r demod
+ * cxd2820r_attach - Attach a cxd2820r demod
  *
  * @config: pointer to &struct cxd2820r_config with demod configuration.
  * @i2c: i2c adapter to use.
diff --git a/drivers/media/dvb-frontends/drxk.h b/drivers/media/dvb-frontends/drxk.h
index ee06e89187e4..69fdca00f364 100644
--- a/drivers/media/dvb-frontends/drxk.h
+++ b/drivers/media/dvb-frontends/drxk.h
@@ -54,7 +54,7 @@ struct drxk_config {
 
 #if IS_REACHABLE(CONFIG_DVB_DRXK)
 /**
- * Attach a drxk demod
+ * drxk_attach - Attach a drxk demod
  *
  * @config: pointer to &struct drxk_config with demod configuration.
  * @i2c: i2c adapter to use.
diff --git a/drivers/media/dvb-frontends/dvb-pll.h b/drivers/media/dvb-frontends/dvb-pll.h
index 973a66a82e27..71838888743b 100644
--- a/drivers/media/dvb-frontends/dvb-pll.h
+++ b/drivers/media/dvb-frontends/dvb-pll.h
@@ -38,7 +38,7 @@ struct dvb_pll_config {
 
 #if IS_REACHABLE(CONFIG_DVB_PLL)
 /**
- * Attach a dvb-pll to the supplied frontend structure.
+ * dvb_pll_attach - Attach a dvb-pll to the supplied frontend structure.
  *
  * @fe: Frontend to attach to.
  * @pll_addr: i2c address of the PLL (if used).
diff --git a/drivers/media/dvb-frontends/helene.h b/drivers/media/dvb-frontends/helene.h
index c026bdcf548d..32e0b1fb268c 100644
--- a/drivers/media/dvb-frontends/helene.h
+++ b/drivers/media/dvb-frontends/helene.h
@@ -44,7 +44,7 @@ struct helene_config {
 
 #if IS_REACHABLE(CONFIG_DVB_HELENE)
 /**
- * Attach a helene tuner (terrestrial and cable standards)
+ * helene_attach - Attach a helene tuner (terrestrial and cable standards)
  *
  * @fe: frontend to be attached
  * @config: pointer to &struct helene_config with tuner configuration.
@@ -57,7 +57,7 @@ extern struct dvb_frontend *helene_attach(struct dvb_frontend *fe,
 					struct i2c_adapter *i2c);
 
 /**
- * Attach a helene tuner (satellite standards)
+ * helene_attach_s - Attach a helene tuner (satellite standards)
  *
  * @fe: frontend to be attached
  * @config: pointer to &struct helene_config with tuner configuration.
diff --git a/drivers/media/dvb-frontends/horus3a.h b/drivers/media/dvb-frontends/horus3a.h
index 366c399e3329..91dbe20169cd 100644
--- a/drivers/media/dvb-frontends/horus3a.h
+++ b/drivers/media/dvb-frontends/horus3a.h
@@ -33,7 +33,7 @@ struct horus3a_config {
 
 #if IS_REACHABLE(CONFIG_DVB_HORUS3A)
 /**
- * Attach a horus3a tuner
+ * horus3a_attach - Attach a horus3a tuner
  *
  * @fe: frontend to be attached
  * @config: pointer to &struct helene_config with tuner configuration.
diff --git a/drivers/media/dvb-frontends/ix2505v.h b/drivers/media/dvb-frontends/ix2505v.h
index 671c0e0959f7..175569131365 100644
--- a/drivers/media/dvb-frontends/ix2505v.h
+++ b/drivers/media/dvb-frontends/ix2505v.h
@@ -1,5 +1,5 @@
 /* SPDX-License-Identifier: GPL-2.0-only */
-/**
+/*
  * Driver for Sharp IX2505V (marked B0017) DVB-S silicon tuner
  *
  * Copyright (C) 2010 Malcolm Priestley
@@ -31,7 +31,7 @@ struct ix2505v_config {
 
 #if IS_REACHABLE(CONFIG_DVB_IX2505V)
 /**
- * Attach a ix2505v tuner to the supplied frontend structure.
+ * ix2505v_attach - Attach a ix2505v tuner to the supplied frontend structure.
  *
  * @fe: Frontend to attach to.
  * @config: pointer to &struct ix2505v_config
diff --git a/drivers/media/dvb-frontends/m88ds3103.h b/drivers/media/dvb-frontends/m88ds3103.h
index 46b722495e4c..e32b68c0df70 100644
--- a/drivers/media/dvb-frontends/m88ds3103.h
+++ b/drivers/media/dvb-frontends/m88ds3103.h
@@ -128,7 +128,7 @@ struct m88ds3103_config {
 #if defined(CONFIG_DVB_M88DS3103) || \
 		(defined(CONFIG_DVB_M88DS3103_MODULE) && defined(MODULE))
 /**
- * Attach a m88ds3103 demod
+ * m88ds3103_attach - Attach a m88ds3103 demod
  *
  * @config: pointer to &struct m88ds3103_config with demod configuration.
  * @i2c: i2c adapter to use.
diff --git a/drivers/media/dvb-frontends/mb86a20s.h b/drivers/media/dvb-frontends/mb86a20s.h
index 00a6b6e9b5e4..d20d22bf7580 100644
--- a/drivers/media/dvb-frontends/mb86a20s.h
+++ b/drivers/media/dvb-frontends/mb86a20s.h
@@ -26,7 +26,7 @@ struct mb86a20s_config {
 
 #if IS_REACHABLE(CONFIG_DVB_MB86A20S)
 /**
- * Attach a mb86a20s demod
+ * mb86a20s_attach - Attach a mb86a20s demod
  *
  * @config: pointer to &struct mb86a20s_config with demod configuration.
  * @i2c: i2c adapter to use.
diff --git a/drivers/media/dvb-frontends/stb6000.h b/drivers/media/dvb-frontends/stb6000.h
index 570a4b1d07d6..38da55af7ea9 100644
--- a/drivers/media/dvb-frontends/stb6000.h
+++ b/drivers/media/dvb-frontends/stb6000.h
@@ -15,7 +15,7 @@
 
 #if IS_REACHABLE(CONFIG_DVB_STB6000)
 /**
- * Attach a stb6000 tuner to the supplied frontend structure.
+ * stb6000_attach - Attach a stb6000 tuner to the supplied frontend structure.
  *
  * @fe: Frontend to attach to.
  * @addr: i2c address of the tuner.
diff --git a/drivers/media/dvb-frontends/tda826x.h b/drivers/media/dvb-frontends/tda826x.h
index bb575a251b04..e1d33edbb8ec 100644
--- a/drivers/media/dvb-frontends/tda826x.h
+++ b/drivers/media/dvb-frontends/tda826x.h
@@ -14,7 +14,7 @@
 #include <media/dvb_frontend.h>
 
 /**
- * Attach a tda826x tuner to the supplied frontend structure.
+ * tda826x_attach - Attach a tda826x tuner to the supplied frontend structure.
  *
  * @fe: Frontend to attach to.
  * @addr: i2c address of the tuner.
diff --git a/drivers/media/dvb-frontends/zl10036.h b/drivers/media/dvb-frontends/zl10036.h
index 91eea777eaf1..ad83e6344e7f 100644
--- a/drivers/media/dvb-frontends/zl10036.h
+++ b/drivers/media/dvb-frontends/zl10036.h
@@ -1,5 +1,5 @@
 /* SPDX-License-Identifier: GPL-2.0-only */
-/**
+/*
  * Driver for Zarlink ZL10036 DVB-S silicon tuner
  *
  * Copyright (C) 2006 Tino Reichardt
@@ -19,7 +19,7 @@ struct zl10036_config {
 
 #if IS_REACHABLE(CONFIG_DVB_ZL10036)
 /**
- * Attach a zl10036 tuner to the supplied frontend structure.
+ * zl10036_attach - Attach a zl10036 tuner to the supplied frontend structure.
  *
  * @fe: Frontend to attach to.
  * @config: zl10036_config structure.
diff --git a/drivers/staging/media/ipu3/include/intel-ipu3.h b/drivers/staging/media/ipu3/include/intel-ipu3.h
index 3a45c1fe4957..edd8edda0647 100644
--- a/drivers/staging/media/ipu3/include/intel-ipu3.h
+++ b/drivers/staging/media/ipu3/include/intel-ipu3.h
@@ -418,7 +418,7 @@ struct ipu3_uapi_af_config_s {
 	 IPU3_UAPI_AWB_FR_SPARE_FOR_BUBBLES) * IPU3_UAPI_MAX_STRIPES)
 
 /**
- * struct ipu3_uapi_awb_fr_meta_data - AWB filter response meta data
+ * struct ipu3_uapi_awb_fr_raw_buffer - AWB filter response meta data
  *
  * @meta_data: Statistics output on the grid after convolving with 1D filter.
  */
@@ -1506,7 +1506,7 @@ struct ipu3_uapi_sharp_cfg {
 } __packed;
 
 /**
- * struct struct ipu3_uapi_far_w - Sharpening config for far sub-group
+ * struct ipu3_uapi_far_w - Sharpening config for far sub-group
  *
  * @dir_shrp:	Weight of wide direct sharpening, u1.6, range [0, 64], default 64.
  * @reserved0:	reserved
@@ -1526,7 +1526,7 @@ struct ipu3_uapi_far_w {
 } __packed;
 
 /**
- * struct struct ipu3_uapi_unsharp_cfg - Unsharp config
+ * struct ipu3_uapi_unsharp_cfg - Unsharp config
  *
  * @unsharp_weight: Unsharp mask blending weight.
  *		    u1.6, range [0, 64], default 16.
@@ -1772,7 +1772,7 @@ struct ipu3_uapi_vss_lut_y {
 } __packed;
 
 /**
- * struct ipu3_uapi_yuvp1_iefd_vssnlm_cf - IEFd Vssnlm Lookup table
+ * struct ipu3_uapi_yuvp1_iefd_vssnlm_cfg - IEFd Vssnlm Lookup table
  *
  * @vss_lut_x: vss lookup table. See &ipu3_uapi_vss_lut_x description
  * @vss_lut_y: vss lookup table. See &ipu3_uapi_vss_lut_y description
diff --git a/include/media/dvbdev.h b/include/media/dvbdev.h
index e547cbeee431..b04a38be5183 100644
--- a/include/media/dvbdev.h
+++ b/include/media/dvbdev.h
@@ -321,7 +321,7 @@ int dvb_create_media_graph(struct dvb_adapter *adap,
 int dvb_generic_open(struct inode *inode, struct file *file);
 
 /**
- * dvb_generic_close - Digital TV close function, used by DVB devices
+ * dvb_generic_release - Digital TV close function, used by DVB devices
  *
  * @inode: pointer to &struct inode.
  * @file: pointer to &struct file.
diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
index cb25f345e9ad..4fbace0fc7e5 100644
--- a/include/media/v4l2-ctrls.h
+++ b/include/media/v4l2-ctrls.h
@@ -1292,7 +1292,7 @@ static inline void v4l2_ctrl_request_hdl_put(struct v4l2_ctrl_handler *hdl)
 }
 
 /**
- * v4l2_ctrl_request_ctrl_find() - Find a control with the given ID.
+ * v4l2_ctrl_request_hdl_ctrl_find() - Find a control with the given ID.
  *
  * @hdl: The control handler from the request.
  * @id: The ID of the control to find.
diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
index ad2d41952442..6a4afd4a7df2 100644
--- a/include/media/v4l2-dev.h
+++ b/include/media/v4l2-dev.h
@@ -43,8 +43,8 @@ enum vfl_devnode_type {
 };
 
 /**
- * enum  vfl_direction - Identifies if a &struct video_device corresponds
- *	to a receiver, a transmitter or a mem-to-mem device.
+ * enum  vfl_devnode_direction - Identifies if a &struct video_device
+ * 	corresponds to a receiver, a transmitter or a mem-to-mem device.
  *
  * @VFL_DIR_RX:		device is a receiver.
  * @VFL_DIR_TX:		device is a transmitter.
diff --git a/include/media/v4l2-device.h b/include/media/v4l2-device.h
index 64ec4de948e9..8a8977a33ec1 100644
--- a/include/media/v4l2-device.h
+++ b/include/media/v4l2-device.h
@@ -174,7 +174,7 @@ int __must_check v4l2_device_register_subdev(struct v4l2_device *v4l2_dev,
 void v4l2_device_unregister_subdev(struct v4l2_subdev *sd);
 
 /**
- * __v4l2_device_register_ro_subdev_nodes - Registers device nodes for
+ * __v4l2_device_register_subdev_nodes - Registers device nodes for
  *      all subdevs of the v4l2 device that are marked with the
  *      %V4L2_SUBDEV_FL_HAS_DEVNODE flag.
  *
diff --git a/include/media/v4l2-dv-timings.h b/include/media/v4l2-dv-timings.h
index 2cc0cabc124f..8fa963326bf6 100644
--- a/include/media/v4l2-dv-timings.h
+++ b/include/media/v4l2-dv-timings.h
@@ -224,7 +224,7 @@ static inline  bool can_reduce_fps(struct v4l2_bt_timings *bt)
 }
 
 /**
- * struct v4l2_hdmi_rx_colorimetry - describes the HDMI colorimetry information
+ * struct v4l2_hdmi_colorimetry - describes the HDMI colorimetry information
  * @colorspace:		enum v4l2_colorspace, the colorspace
  * @ycbcr_enc:		enum v4l2_ycbcr_encoding, Y'CbCr encoding
  * @quantization:	enum v4l2_quantization, colorspace quantization
diff --git a/include/media/v4l2-fwnode.h b/include/media/v4l2-fwnode.h
index c09074276543..4c1f213180dc 100644
--- a/include/media/v4l2-fwnode.h
+++ b/include/media/v4l2-fwnode.h
@@ -514,7 +514,7 @@ v4l2_async_notifier_parse_fwnode_endpoints_by_port(struct device *dev,
 						   parse_endpoint_func parse_endpoint);
 
 /**
- * v4l2_fwnode_reference_parse_sensor_common - parse common references on
+ * v4l2_async_notifier_parse_fwnode_sensor_common - parse common references on
  *					       sensors for async sub-devices
  * @dev: the device node the properties of which are parsed for references
  * @notifier: the async notifier where the async subdevs will be added
diff --git a/include/media/v4l2-mediabus.h b/include/media/v4l2-mediabus.h
index 59b1de197114..2014c5911aac 100644
--- a/include/media/v4l2-mediabus.h
+++ b/include/media/v4l2-mediabus.h
@@ -145,7 +145,7 @@ v4l2_fill_pix_format(struct v4l2_pix_format *pix_fmt,
 }
 
 /**
- * v4l2_fill_pix_format - Ancillary routine that fills a &struct
+ * v4l2_fill_mbus_format - Ancillary routine that fills a &struct
  *	v4l2_mbus_framefmt from a &struct v4l2_pix_format and a
  *	data format code.
  *
@@ -168,7 +168,7 @@ static inline void v4l2_fill_mbus_format(struct v4l2_mbus_framefmt *mbus_fmt,
 }
 
 /**
- * v4l2_fill_pix_format - Ancillary routine that fills a &struct
+ * v4l2_fill_pix_format_mplane - Ancillary routine that fills a &struct
  *	v4l2_pix_format_mplane fields from a media bus structure.
  *
  * @pix_mp_fmt:	pointer to &struct v4l2_pix_format_mplane to be filled
@@ -188,7 +188,7 @@ v4l2_fill_pix_format_mplane(struct v4l2_pix_format_mplane *pix_mp_fmt,
 }
 
 /**
- * v4l2_fill_pix_format - Ancillary routine that fills a &struct
+ * v4l2_fill_mbus_format_mplane - Ancillary routine that fills a &struct
  *	v4l2_mbus_framefmt from a &struct v4l2_pix_format_mplane.
  *
  * @mbus_fmt:	pointer to &struct v4l2_mbus_framefmt to be filled
diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index 1de960bfcab9..d0e9a5bdb08b 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -309,7 +309,7 @@ struct v4l2_subdev_audio_ops {
 };
 
 /**
- * enum v4l2_mbus_frame_desc_entry - media bus frame description flags
+ * enum v4l2_mbus_frame_desc_flags - media bus frame description flags
  *
  * @V4L2_MBUS_FRAME_DESC_FL_LEN_MAX:
  *	Indicates that &struct v4l2_mbus_frame_desc_entry->length field
diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index bbb3f26fbde9..61969402a0e3 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -1043,7 +1043,7 @@ __poll_t vb2_core_poll(struct vb2_queue *q, struct file *file,
 size_t vb2_read(struct vb2_queue *q, char __user *data, size_t count,
 		loff_t *ppos, int nonblock);
 /**
- * vb2_read() - implements write() syscall logic.
+ * vb2_write() - implements write() syscall logic.
  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
  * @data:	pointed to target userspace buffer
  * @count:	number of bytes to write
-- 
2.26.2

[PATCH v3 16/56] mei: bus: fix a kernel-doc markup

[Mauro Carvalho Chehab]

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/misc/mei/bus.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/misc/mei/bus.c b/drivers/misc/mei/bus.c
index 9cdaa7f3af23..04b904e3a56a 100644
--- a/drivers/misc/mei/bus.c
+++ b/drivers/misc/mei/bus.c
@@ -1037,7 +1037,7 @@ static struct mei_cl_device *mei_cl_bus_dev_alloc(struct mei_device *bus,
 }
 
 /**
- * mei_cl_dev_setup - setup me client device
+ * mei_cl_bus_dev_setup - setup me client device
  *    run fix up routines and set the device name
  *
  * @bus: mei device
-- 
2.26.2

[PATCH v3 17/56] mtd: rawnand: fix a kernel-doc markup

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/mtd/nand/raw/nand_bbt.c | 2 +-
 include/linux/mtd/rawnand.h     | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/drivers/mtd/nand/raw/nand_bbt.c b/drivers/mtd/nand/raw/nand_bbt.c
index 344a24fd2ca8..dced32a126d9 100644
--- a/drivers/mtd/nand/raw/nand_bbt.c
+++ b/drivers/mtd/nand/raw/nand_bbt.c
@@ -1087,7 +1087,7 @@ static int nand_update_bbt(struct nand_chip *this, loff_t offs)
 }
 
 /**
- * mark_bbt_regions - [GENERIC] mark the bad block table regions
+ * mark_bbt_region - [GENERIC] mark the bad block table regions
  * @this: the NAND device
  * @td: bad block table descriptor
  *
diff --git a/include/linux/mtd/rawnand.h b/include/linux/mtd/rawnand.h
index aac07940de09..ace1ce70f5e4 100644
--- a/include/linux/mtd/rawnand.h
+++ b/include/linux/mtd/rawnand.h
@@ -1286,7 +1286,8 @@ static inline bool nand_is_slc(struct nand_chip *chip)
 }
 
 /**
- * Check if the opcode's address should be sent only on the lower 8 bits
+ * nand_opcode_8bits - Check if the opcode's address should be sent only on the
+ *	lower 8 bits
  * @command: opcode to check
  */
 static inline int nand_opcode_8bits(unsigned int command)
-- 
2.26.2

[PATCH v3 18/56] net: phy: fix kernel-doc markups

[Mauro Carvalho Chehab]

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

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
@@ -472,7 +472,7 @@ static inline void of_mdiobus_link_mdiodev(struct mii_bus *mdio,
 #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
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
@@ -9,7 +9,7 @@
 #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)
diff --git a/drivers/net/phy/phy.c b/drivers/net/phy/phy.c
index 35525a671400..71ed2596acf5 100644
--- a/drivers/net/phy/phy.c
+++ b/drivers/net/phy/phy.c
@@ -489,7 +489,7 @@ void phy_queue_state_machine(struct phy_device *phydev, unsigned long 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
  */
diff --git a/drivers/net/phy/phy_device.c b/drivers/net/phy/phy_device.c
index 5dab6be6fc38..ea5d5fb42d01 100644
--- a/drivers/net/phy/phy_device.c
+++ b/drivers/net/phy/phy_device.c
@@ -2735,7 +2735,7 @@ static int phy_get_int_delay_property(struct device *dev, const char *name)
 #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
diff --git a/drivers/net/phy/phylink.c b/drivers/net/phy/phylink.c
index fe2296fdda19..1318ccb62bd7 100644
--- a/drivers/net/phy/phylink.c
+++ b/drivers/net/phy/phylink.c
@@ -1649,7 +1649,7 @@ int phylink_ethtool_set_pauseparam(struct phylink *pl,
 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().
  *
-- 
2.26.2

[PATCH v3 19/56] net: datagram: fix some kernel-doc markups

[Mauro Carvalho Chehab]

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

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

diff --git a/net/core/datagram.c b/net/core/datagram.c
index 9fcaa544f11a..81809fa735a7 100644
--- a/net/core/datagram.c
+++ b/net/core/datagram.c
@@ -709,7 +709,7 @@ int zerocopy_sg_from_iter(struct sk_buff *skb, struct iov_iter *from)
 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
diff --git a/net/core/dev.c b/net/core/dev.c
index 751e5264fd49..75c879f8ab3f 100644
--- a/net/core/dev.c
+++ b/net/core/dev.c
@@ -6915,7 +6915,7 @@ bool netdev_has_upper_dev(struct net_device *dev,
 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
  *
@@ -8153,7 +8153,7 @@ 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
  *
diff --git a/net/core/skbuff.c b/net/core/skbuff.c
index 1ba8f0163744..49da6b259444 100644
--- a/net/core/skbuff.c
+++ b/net/core/skbuff.c
@@ -837,7 +837,7 @@ 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
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
@@ -272,7 +272,7 @@ void eth_header_cache_update(struct hh_cache *hh,
 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)
@@ -523,8 +523,8 @@ int eth_platform_get_mac_address(struct device *dev, u8 *mac_addr)
 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.
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
@@ -781,7 +781,8 @@ static int rpc_rmdir_depopulate(struct dentry *dentry,
 }
 
 /**
- * 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
-- 
2.26.2

[PATCH v3 20/56] net: core: fix some kernel-doc markups

[Mauro Carvalho Chehab]

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

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

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

diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
index 964b494b0e8d..db79ab7580dd 100644
--- a/include/linux/netdevice.h
+++ b/include/linux/netdevice.h
@@ -1490,7 +1490,7 @@ struct net_device_ops {
 };
 
 /**
- * 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
@@ -3576,7 +3576,7 @@ static inline void netif_stop_subqueue(struct net_device *dev, u16 queue_index)
 }
 
 /**
- *	netif_subqueue_stopped - test status of subqueue
+ *	__netif_subqueue_stopped - test status of subqueue
  *	@dev: network device
  *	@queue_index: sub queue index
  *
@@ -3590,6 +3590,13 @@ static inline bool __netif_subqueue_stopped(const struct net_device *dev,
 	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)
 {
-- 
2.26.2

[PATCH v3 21/56] mac80211: fix kernel-doc markups

[Mauro Carvalho Chehab]

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

In the specific case of __sta_info_flush(), add a documentation
for sta_info_flush(), as this one is the one used outside
sta_info.c.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/net/cfg80211.h  | 9 +++++----
 include/net/mac80211.h  | 7 ++++---
 net/mac80211/sta_info.h | 9 ++++++++-
 3 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 661edfc8722e..d5ab8d99739f 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -1444,7 +1444,7 @@ int cfg80211_check_station_change(struct wiphy *wiphy,
 				  enum cfg80211_station_type statype);
 
 /**
- * enum station_info_rate_flags - bitrate info flags
+ * enum rate_info_flags - bitrate info flags
  *
  * Used by the driver to indicate the specific rate transmission
  * type for 802.11n transmissions.
@@ -1517,7 +1517,7 @@ struct rate_info {
 };
 
 /**
- * enum station_info_rate_flags - bitrate info flags
+ * enum bss_param_flags - bitrate info flags
  *
  * Used by the driver to indicate the specific rate transmission
  * type for 802.11n transmissions.
@@ -6467,7 +6467,8 @@ void cfg80211_ibss_joined(struct net_device *dev, const u8 *bssid,
 			  struct ieee80211_channel *channel, gfp_t gfp);
 
 /**
- * cfg80211_notify_new_candidate - notify cfg80211 of a new mesh peer candidate
+ * cfg80211_notify_new_peer_candidate - notify cfg80211 of a new mesh peer
+ * 					candidate
  *
  * @dev: network device
  * @macaddr: the MAC address of the new candidate
@@ -7606,7 +7607,7 @@ u32 cfg80211_calculate_bitrate(struct rate_info *rate);
 void cfg80211_unregister_wdev(struct wireless_dev *wdev);
 
 /**
- * struct cfg80211_ft_event - FT Information Elements
+ * struct cfg80211_ft_event_params - FT Information Elements
  * @ies: FT IEs
  * @ies_len: length of the FT IE in bytes
  * @target_ap: target AP's MAC address
diff --git a/include/net/mac80211.h b/include/net/mac80211.h
index e8e295dae744..dcdba96814a2 100644
--- a/include/net/mac80211.h
+++ b/include/net/mac80211.h
@@ -3311,7 +3311,7 @@ enum ieee80211_roc_type {
 };
 
 /**
- * enum ieee80211_reconfig_complete_type - reconfig type
+ * enum ieee80211_reconfig_type - reconfig type
  *
  * This enum is used by the reconfig_complete() callback to indicate what
  * reconfiguration type was completed.
@@ -6334,7 +6334,8 @@ bool ieee80211_tx_prepare_skb(struct ieee80211_hw *hw,
 			      int band, struct ieee80211_sta **sta);
 
 /**
- * Sanity-check and parse the radiotap header of injected frames
+ * ieee80211_parse_tx_radiotap - Sanity-check and parse the radiotap header
+ *				 of injected frames
  * @skb: packet injected by userspace
  * @dev: the &struct device of this 802.11 device
  */
@@ -6389,7 +6390,7 @@ int ieee80211_parse_p2p_noa(const struct ieee80211_p2p_noa_attr *attr,
 void ieee80211_update_p2p_noa(struct ieee80211_noa_data *data, u32 tsf);
 
 /**
- * ieee80211_tdls_oper - request userspace to perform a TDLS operation
+ * ieee80211_tdls_oper_request - request userspace to perform a TDLS operation
  * @vif: virtual interface
  * @peer: the peer's destination address
  * @oper: the requested TDLS operation
diff --git a/net/mac80211/sta_info.h b/net/mac80211/sta_info.h
index 00ae81e9e1a1..7afd07636b81 100644
--- a/net/mac80211/sta_info.h
+++ b/net/mac80211/sta_info.h
@@ -785,7 +785,7 @@ int sta_info_init(struct ieee80211_local *local);
 void sta_info_stop(struct ieee80211_local *local);
 
 /**
- * sta_info_flush - flush matching STA entries from the STA table
+ * __sta_info_flush - flush matching STA entries from the STA table
  *
  * Returns the number of removed STA entries.
  *
@@ -794,6 +794,13 @@ void sta_info_stop(struct ieee80211_local *local);
  */
 int __sta_info_flush(struct ieee80211_sub_if_data *sdata, bool vlans);
 
+/**
+ * sta_info_flush - flush matching STA entries from the STA table
+ *
+ * Returns the number of removed STA entries.
+ *
+ * @sdata: sdata to remove all stations from
+ */
 static inline int sta_info_flush(struct ieee80211_sub_if_data *sdata)
 {
 	return __sta_info_flush(sdata, false);
-- 
2.26.2

[PATCH v3 22/56] parport: fix a kernel-doc markup

[Mauro Carvalho Chehab]

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
@@ -243,7 +243,7 @@ static int port_detect(struct device *dev, void *dev_drv)
 }
 
 /**
- *	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
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
@@ -297,6 +297,37 @@ int __must_check __parport_register_driver(struct parport_driver *,
  * 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)
 
-- 
2.26.2

[PATCH v3 23/56] PCI: fix kernel-doc markups

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/pci/p2pdma.c     | 10 +++++-----
 drivers/pci/pci-driver.c |  4 ++--
 drivers/pci/pci.c        |  2 +-
 drivers/pci/probe.c      |  4 ++--
 drivers/pci/slot.c       |  5 +++--
 5 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/drivers/pci/p2pdma.c b/drivers/pci/p2pdma.c
index de1c331dbed4..bace04145c5f 100644
--- a/drivers/pci/p2pdma.c
+++ b/drivers/pci/p2pdma.c
@@ -609,7 +609,7 @@ bool pci_has_p2pmem(struct pci_dev *pdev)
 EXPORT_SYMBOL_GPL(pci_has_p2pmem);
 
 /**
- * pci_p2pmem_find - find a peer-to-peer DMA memory device compatible with
+ * pci_p2pmem_find_many - find a peer-to-peer DMA memory device compatible with
  *	the specified list of clients and shortest distance (as determined
  *	by pci_p2pmem_dma())
  * @clients: array of devices to check (NULL-terminated)
@@ -674,7 +674,7 @@ struct pci_dev *pci_p2pmem_find_many(struct device **clients, int num_clients)
 EXPORT_SYMBOL_GPL(pci_p2pmem_find_many);
 
 /**
- * pci_alloc_p2p_mem - allocate peer-to-peer DMA memory
+ * pci_alloc_p2pmem - allocate peer-to-peer DMA memory
  * @pdev: the device to allocate memory from
  * @size: number of bytes to allocate
  *
@@ -727,7 +727,7 @@ void pci_free_p2pmem(struct pci_dev *pdev, void *addr, size_t size)
 EXPORT_SYMBOL_GPL(pci_free_p2pmem);
 
 /**
- * pci_virt_to_bus - return the PCI bus address for a given virtual
+ * pci_p2pmem_virt_to_bus - return the PCI bus address for a given virtual
  *	address obtained with pci_alloc_p2pmem()
  * @pdev: the device the memory was allocated from
  * @addr: address of the memory that was allocated
@@ -859,7 +859,7 @@ static int __pci_p2pdma_map_sg(struct pci_p2pdma_pagemap *p2p_pgmap,
 }
 
 /**
- * pci_p2pdma_map_sg - map a PCI peer-to-peer scatterlist for DMA
+ * pci_p2pdma_map_sg_attrs - map a PCI peer-to-peer scatterlist for DMA
  * @dev: device doing the DMA request
  * @sg: scatter list to map
  * @nents: elements in the scatterlist
@@ -896,7 +896,7 @@ int pci_p2pdma_map_sg_attrs(struct device *dev, struct scatterlist *sg,
 EXPORT_SYMBOL_GPL(pci_p2pdma_map_sg_attrs);
 
 /**
- * pci_p2pdma_unmap_sg - unmap a PCI peer-to-peer scatterlist that was
+ * pci_p2pdma_unmap_sg_attrs - unmap a PCI peer-to-peer scatterlist that was
  *	mapped with pci_p2pdma_map_sg()
  * @dev: device doing the DMA request
  * @sg: scatter list to map
diff --git a/drivers/pci/pci-driver.c b/drivers/pci/pci-driver.c
index 8b587fc97f7b..591ab353844a 100644
--- a/drivers/pci/pci-driver.c
+++ b/drivers/pci/pci-driver.c
@@ -90,7 +90,7 @@ static void pci_free_dynids(struct pci_driver *drv)
 }
 
 /**
- * store_new_id - sysfs frontend to pci_add_dynid()
+ * new_id_store - sysfs frontend to pci_add_dynid()
  * @driver: target device driver
  * @buf: buffer for scanning device ID data
  * @count: input size
@@ -158,7 +158,7 @@ static ssize_t new_id_store(struct device_driver *driver, const char *buf,
 static DRIVER_ATTR_WO(new_id);
 
 /**
- * store_remove_id - remove a PCI device ID from this driver
+ * remove_id_store - remove a PCI device ID from this driver
  * @driver: target device driver
  * @buf: buffer for scanning device ID data
  * @count: input size
diff --git a/drivers/pci/pci.c b/drivers/pci/pci.c
index 6d4d5a2f923d..8b9bea8ba751 100644
--- a/drivers/pci/pci.c
+++ b/drivers/pci/pci.c
@@ -3480,7 +3480,7 @@ bool pci_acs_enabled(struct pci_dev *pdev, u16 acs_flags)
 }
 
 /**
- * pci_acs_path_enable - test ACS flags from start to end in a hierarchy
+ * pci_acs_path_enabled - test ACS flags from start to end in a hierarchy
  * @start: starting downstream device
  * @end: ending upstream device or NULL to search to the root bus
  * @acs_flags: required flags
diff --git a/drivers/pci/probe.c b/drivers/pci/probe.c
index 4289030b0fff..eb1ec037f9e7 100644
--- a/drivers/pci/probe.c
+++ b/drivers/pci/probe.c
@@ -165,7 +165,7 @@ static inline unsigned long decode_bar(struct pci_dev *dev, u32 bar)
 #define PCI_COMMAND_DECODE_ENABLE	(PCI_COMMAND_MEMORY | PCI_COMMAND_IO)
 
 /**
- * pci_read_base - Read a PCI BAR
+ * __pci_read_base - Read a PCI BAR
  * @dev: the PCI device
  * @type: type of the BAR
  * @res: resource buffer to be filled in
@@ -1612,7 +1612,7 @@ static bool pci_ext_cfg_is_aliased(struct pci_dev *dev)
 }
 
 /**
- * pci_cfg_space_size - Get the configuration space size of the PCI device
+ * pci_cfg_space_size_ext - Get the configuration space size of the PCI device
  * @dev: PCI device
  *
  * Regular PCI devices have 256 bytes, but PCI-X 2 and PCI Express devices
diff --git a/drivers/pci/slot.c b/drivers/pci/slot.c
index 3861505741e6..bcc8b12ce5da 100644
--- a/drivers/pci/slot.c
+++ b/drivers/pci/slot.c
@@ -323,7 +323,7 @@ EXPORT_SYMBOL_GPL(pci_destroy_slot);
 #if defined(CONFIG_HOTPLUG_PCI) || defined(CONFIG_HOTPLUG_PCI_MODULE)
 #include <linux/pci_hotplug.h>
 /**
- * pci_hp_create_link - create symbolic link to the hotplug driver module.
+ * pci_hp_create_module_link - create symbolic link to the hotplug driver module.
  * @pci_slot: struct pci_slot
  *
  * Helper function for pci_hotplug_core.c to create symbolic link to
@@ -349,7 +349,8 @@ void pci_hp_create_module_link(struct pci_slot *pci_slot)
 EXPORT_SYMBOL_GPL(pci_hp_create_module_link);
 
 /**
- * pci_hp_remove_link - remove symbolic link to the hotplug driver module.
+ * pci_hp_remove_module_link - remove symbolic link to the hotplug driver
+ * 	module.
  * @pci_slot: struct pci_slot
  *
  * Helper function for pci_hotplug_core.c to remove symbolic link to
-- 
2.26.2

[PATCH v3 24/56] PNP: fix kernel-doc markups

[Mauro Carvalho Chehab]

It sounds that there were function renames. Update the kernel-doc
markups accordingly.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/pnp/core.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/pnp/core.c b/drivers/pnp/core.c
index 3bf18d718975..a50ab002e9e4 100644
--- a/drivers/pnp/core.c
+++ b/drivers/pnp/core.c
@@ -51,7 +51,7 @@ static void pnp_remove_protocol(struct pnp_protocol *protocol)
 }
 
 /**
- * pnp_protocol_register - adds a pnp protocol to the pnp layer
+ * pnp_register_protocol - adds a pnp protocol to the pnp layer
  * @protocol: pointer to the corresponding pnp_protocol structure
  *
  *  Ex protocols: ISAPNP, PNPBIOS, etc
@@ -91,7 +91,7 @@ int pnp_register_protocol(struct pnp_protocol *protocol)
 }
 
 /**
- * pnp_protocol_unregister - removes a pnp protocol from the pnp layer
+ * pnp_unregister_protocol - removes a pnp protocol from the pnp layer
  * @protocol: pointer to the corresponding pnp_protocol structure
  */
 void pnp_unregister_protocol(struct pnp_protocol *protocol)
-- 
2.26.2

[PATCH v3 25/56] rapidio: fix kernel-doc a markup

[Mauro Carvalho Chehab]

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
@@ -749,7 +749,7 @@ int rio_map_outb_region(struct rio_mport *mport, u16 destid, u64 rbase,
 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
-- 
2.26.2

[PATCH v3 26/56] regulator: fix a kernel-doc markup

[Mauro Carvalho Chehab]

It seems that the function was renamed. kernel-doc markup
should follow it.

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

diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c
index a4ffd71696da..79d00e7039d9 100644
--- a/drivers/regulator/core.c
+++ b/drivers/regulator/core.c
@@ -5529,7 +5529,7 @@ void regulator_set_drvdata(struct regulator *regulator, void *data)
 EXPORT_SYMBOL_GPL(regulator_set_drvdata);
 
 /**
- * regulator_get_id - get regulator ID
+ * rdev_get_id - get regulator ID
  * @rdev: regulator
  */
 int rdev_get_id(struct regulator_dev *rdev)
-- 
2.26.2

[PATCH v3 27/56] scsi: fix some kernel-doc markups

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/scsi/iscsi_tcp.c         | 4 ++--
 drivers/scsi/libiscsi.c          | 2 +-
 drivers/scsi/scsi_devinfo.c      | 3 ++-
 drivers/scsi/scsi_lib.c          | 6 +++---
 drivers/scsi/scsi_transport_fc.c | 2 +-
 5 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/drivers/scsi/iscsi_tcp.c b/drivers/scsi/iscsi_tcp.c
index df47557a02a3..a9ce6298b935 100644
--- a/drivers/scsi/iscsi_tcp.c
+++ b/drivers/scsi/iscsi_tcp.c
@@ -180,7 +180,7 @@ static void iscsi_sw_tcp_state_change(struct sock *sk)
 }
 
 /**
- * iscsi_write_space - Called when more output buffer space is available
+ * iscsi_sw_tcp_write_space - Called when more output buffer space is available
  * @sk: socket space is available for
  **/
 static void iscsi_sw_tcp_write_space(struct sock *sk)
@@ -353,7 +353,7 @@ static int iscsi_sw_tcp_xmit(struct iscsi_conn *conn)
 }
 
 /**
- * iscsi_tcp_xmit_qlen - return the number of bytes queued for xmit
+ * iscsi_sw_tcp_xmit_qlen - return the number of bytes queued for xmit
  * @conn: iscsi connection
  */
 static inline int iscsi_sw_tcp_xmit_qlen(struct iscsi_conn *conn)
diff --git a/drivers/scsi/libiscsi.c b/drivers/scsi/libiscsi.c
index 1e9c3171fa9f..8a4552f09dfe 100644
--- a/drivers/scsi/libiscsi.c
+++ b/drivers/scsi/libiscsi.c
@@ -777,7 +777,7 @@ int iscsi_conn_send_pdu(struct iscsi_cls_conn *cls_conn, struct iscsi_hdr *hdr,
 EXPORT_SYMBOL_GPL(iscsi_conn_send_pdu);
 
 /**
- * iscsi_cmd_rsp - SCSI Command Response processing
+ * iscsi_scsi_cmd_rsp - SCSI Command Response processing
  * @conn: iscsi connection
  * @hdr: iscsi header
  * @task: scsi command task
diff --git a/drivers/scsi/scsi_devinfo.c b/drivers/scsi/scsi_devinfo.c
index ba84244c1b4f..d92cec12454c 100644
--- a/drivers/scsi/scsi_devinfo.c
+++ b/drivers/scsi/scsi_devinfo.c
@@ -559,7 +559,8 @@ static int scsi_dev_info_list_add_str(char *dev_list)
 }
 
 /**
- * get_device_flags - get device specific flags from the dynamic device list.
+ * scsi_get_device_flags - get device specific flags from the dynamic
+ *	device list.
  * @sdev:       &scsi_device to get flags for
  * @vendor:	vendor name
  * @model:	model name
diff --git a/drivers/scsi/scsi_lib.c b/drivers/scsi/scsi_lib.c
index 97ff31ed2a44..f74db5160f23 100644
--- a/drivers/scsi/scsi_lib.c
+++ b/drivers/scsi/scsi_lib.c
@@ -1502,7 +1502,7 @@ static void scsi_softirq_done(struct request *rq)
 }
 
 /**
- * scsi_dispatch_command - Dispatch a command to the low-level driver.
+ * scsi_dispatch_cmd - Dispatch a command to the low-level driver.
  * @cmd: command block we are dispatching.
  *
  * Return: nonzero return request was rejected and device's queue needs to be
@@ -2364,7 +2364,7 @@ scsi_device_set_state(struct scsi_device *sdev, enum scsi_device_state state)
 EXPORT_SYMBOL(scsi_device_set_state);
 
 /**
- * 	sdev_evt_emit - emit a single SCSI device uevent
+ * 	scsi_evt_emit - emit a single SCSI device uevent
  *	@sdev: associated SCSI device
  *	@evt: event to emit
  *
@@ -2412,7 +2412,7 @@ static void scsi_evt_emit(struct scsi_device *sdev, struct scsi_event *evt)
 }
 
 /**
- * 	sdev_evt_thread - send a uevent for each scsi event
+ * 	scsi_evt_thread - send a uevent for each scsi event
  *	@work: work struct for scsi_device
  *
  *	Dispatch queued events to their associated scsi_device kobjects
diff --git a/drivers/scsi/scsi_transport_fc.c b/drivers/scsi/scsi_transport_fc.c
index 2ff7f06203da..42a6dd3bd19f 100644
--- a/drivers/scsi/scsi_transport_fc.c
+++ b/drivers/scsi/scsi_transport_fc.c
@@ -629,7 +629,7 @@ fc_host_post_vendor_event(struct Scsi_Host *shost, u32 event_number,
 EXPORT_SYMBOL(fc_host_post_vendor_event);
 
 /**
- * fc_host_rcv_fpin - routine to process a received FPIN.
+ * fc_host_fpin_rcv - routine to process a received FPIN.
  * @shost:		host the FPIN was received on
  * @fpin_len:		length of FPIN payload, in bytes
  * @fpin_buf:		pointer to FPIN payload
-- 
2.26.2

[PATCH v3 28/56] slimbus: fix a kernel-doc markup

[Mauro Carvalho Chehab]

Fix the name of the enum on its kernel-doc markup:
	enum slim_ch_aux_fmt -> enum slim_ch_aux_bit_fmt

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

diff --git a/drivers/slimbus/slimbus.h b/drivers/slimbus/slimbus.h
index c73035915f1d..00a7f112574b 100644
--- a/drivers/slimbus/slimbus.h
+++ b/drivers/slimbus/slimbus.h
@@ -244,7 +244,7 @@ enum slim_ch_data_fmt {
 };
 
 /**
- * enum slim_ch_aux_fmt: SLIMbus channel Aux Field format IDs according to
+ * enum slim_ch_aux_bit_fmt: SLIMbus channel Aux Field format IDs according to
  *	Table 63 of SLIMbus Spec 2.0
  * @SLIM_CH_AUX_FMT_NOT_APPLICABLE: Undefined
  * @SLIM_CH_AUX_FMT_ZCUV_TUNNEL_IEC60958: ZCUV for tunneling IEC60958
-- 
2.26.2

[PATCH v3 29/56] spi: fix a typo inside a kernel-doc markup

[Mauro Carvalho Chehab]

spi_split_tranfers_maxsize -> spi_split_transfers_maxsize

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/spi/spi.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/spi/spi.c b/drivers/spi/spi.c
index 0cab239d8e7f..22679c8645db 100644
--- a/drivers/spi/spi.c
+++ b/drivers/spi/spi.c
@@ -3193,9 +3193,9 @@ static int __spi_split_transfer_maxsize(struct spi_controller *ctlr,
 }
 
 /**
- * spi_split_tranfers_maxsize - split spi transfers into multiple transfers
- *                              when an individual transfer exceeds a
- *                              certain size
+ * spi_split_transfers_maxsize - split spi transfers into multiple transfers
+ *                               when an individual transfer exceeds a
+ *                               certain size
  * @ctlr:    the @spi_controller for this transfer
  * @msg:   the @spi_message to transform
  * @maxsize:  the maximum when to apply this
-- 
2.26.2

[PATCH v3 30/56] uio: fix some kernel-doc markups

[Mauro Carvalho Chehab]

The definitions for (devm_)uio_register_device should be
at the header file, as the macros are there. The ones
inside uio.c refer, instead, to __(devm_)uio_register_device.

Update them and add new kernel-doc markups for the macros.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/uio/uio.c          |  4 ++--
 include/linux/uio_driver.h | 16 ++++++++++++++++
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/drivers/uio/uio.c b/drivers/uio/uio.c
index 6dca744e39e9..01b349c1b923 100644
--- a/drivers/uio/uio.c
+++ b/drivers/uio/uio.c
@@ -906,7 +906,7 @@ static void uio_device_release(struct device *dev)
 }
 
 /**
- * uio_register_device - register a new userspace IO device
+ * __uio_register_device - register a new userspace IO device
  * @owner:	module that creates the new device
  * @parent:	parent device
  * @info:	UIO device capabilities
@@ -1002,7 +1002,7 @@ static void devm_uio_unregister_device(struct device *dev, void *res)
 }
 
 /**
- * devm_uio_register_device - Resource managed uio_register_device()
+ * __devm_uio_register_device - Resource managed uio_register_device()
  * @owner:	module that creates the new device
  * @parent:	parent device
  * @info:	UIO device capabilities
diff --git a/include/linux/uio_driver.h b/include/linux/uio_driver.h
index 54bf6b118401..47c5962b876b 100644
--- a/include/linux/uio_driver.h
+++ b/include/linux/uio_driver.h
@@ -117,6 +117,14 @@ extern int __must_check
 			      struct uio_info *info);
 
 /* use a define to avoid include chaining to get THIS_MODULE */
+
+/**
+ * uio_register_device - register a new userspace IO device
+ * @parent:	parent device
+ * @info:	UIO device capabilities
+ *
+ * returns zero on success or a negative error code.
+ */
 #define uio_register_device(parent, info) \
 	__uio_register_device(THIS_MODULE, parent, info)
 
@@ -129,6 +137,14 @@ extern int __must_check
 				   struct uio_info *info);
 
 /* use a define to avoid include chaining to get THIS_MODULE */
+
+/**
+ * devm_uio_register_device - Resource managed uio_register_device()
+ * @parent:	parent device
+ * @info:	UIO device capabilities
+ *
+ * returns zero on success or a negative error code.
+ */
 #define devm_uio_register_device(parent, info) \
 	__devm_uio_register_device(THIS_MODULE, parent, info)
 
-- 
2.26.2

[PATCH v3 31/56] usb: dwc3: fix kernel-doc markups

[Mauro Carvalho Chehab]

There is a common comment marked, instead, with kernel-doc
notation.

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/usb/dwc3/core.c        | 2 +-
 drivers/usb/dwc3/core.h        | 2 +-
 drivers/usb/gadget/composite.c | 2 +-
 drivers/usb/typec/mux.c        | 2 +-
 include/linux/usb/composite.h  | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/drivers/usb/dwc3/core.c b/drivers/usb/dwc3/core.c
index bdf0925da6b6..841daec70b6e 100644
--- a/drivers/usb/dwc3/core.c
+++ b/drivers/usb/dwc3/core.c
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0
-/**
+/*
  * core.c - DesignWare USB3 DRD Controller Core file
  *
  * Copyright (C) 2010-2011 Texas Instruments Incorporated - https://www.ti.com
diff --git a/drivers/usb/dwc3/core.h b/drivers/usb/dwc3/core.h
index 74323b10a64a..2f95f08ca511 100644
--- a/drivers/usb/dwc3/core.h
+++ b/drivers/usb/dwc3/core.h
@@ -1277,7 +1277,7 @@ struct dwc3_event_type {
 #define DWC3_DEPEVT_EPCMDCMPLT		0x07
 
 /**
- * struct dwc3_event_depvt - Device Endpoint Events
+ * struct dwc3_event_depevt - Device Endpoint Events
  * @one_bit: indicates this is an endpoint event (not used)
  * @endpoint_number: number of the endpoint
  * @endpoint_event: The event we have:
diff --git a/drivers/usb/gadget/composite.c b/drivers/usb/gadget/composite.c
index 05b176c82cc5..c6d455f2bb92 100644
--- a/drivers/usb/gadget/composite.c
+++ b/drivers/usb/gadget/composite.c
@@ -1245,7 +1245,7 @@ int usb_string_id(struct usb_composite_dev *cdev)
 EXPORT_SYMBOL_GPL(usb_string_id);
 
 /**
- * usb_string_ids() - allocate unused string IDs in batch
+ * usb_string_ids_tab() - allocate unused string IDs in batch
  * @cdev: the device whose string descriptor IDs are being allocated
  * @str: an array of usb_string objects to assign numbers to
  * Context: single threaded during gadget setup
diff --git a/drivers/usb/typec/mux.c b/drivers/usb/typec/mux.c
index b069a5122aaa..cf720e944aaa 100644
--- a/drivers/usb/typec/mux.c
+++ b/drivers/usb/typec/mux.c
@@ -71,7 +71,7 @@ struct typec_switch *fwnode_typec_switch_get(struct fwnode_handle *fwnode)
 EXPORT_SYMBOL_GPL(fwnode_typec_switch_get);
 
 /**
- * typec_put_switch - Release USB Type-C orientation switch
+ * typec_switch_put - Release USB Type-C orientation switch
  * @sw: USB Type-C orientation switch
  *
  * Decrement reference count for @sw.
diff --git a/include/linux/usb/composite.h b/include/linux/usb/composite.h
index 2040696d75b6..a2d229ab63ba 100644
--- a/include/linux/usb/composite.h
+++ b/include/linux/usb/composite.h
@@ -437,7 +437,7 @@ static inline struct usb_composite_driver *to_cdriver(
 #define OS_STRING_IDX			0xEE
 
 /**
- * struct usb_composite_device - represents one composite usb gadget
+ * struct usb_composite_dev - represents one composite usb gadget
  * @gadget: read-only, abstracts the gadget's usb peripheral controller
  * @req: used for control responses; buffer is pre-allocated
  * @os_desc_req: used for OS descriptors responses; buffer is pre-allocated
-- 
2.26.2

[PATCH v3 32/56] video: fix some kernel-doc markups

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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
@@ -76,7 +76,7 @@ static const struct fb_cmap default_16_colors = {
 
 
 /**
- *	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
diff --git a/drivers/video/hdmi.c b/drivers/video/hdmi.c
index b7a1d6fae90d..e44b7cec95fd 100644
--- a/drivers/video/hdmi.c
+++ b/drivers/video/hdmi.c
@@ -1688,7 +1688,8 @@ static int hdmi_audio_infoframe_unpack(struct hdmi_audio_infoframe *frame,
 }
 
 /**
- * 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
-- 
2.26.2

[PATCH v3 33/56] vme: fix two kernel-doc markups

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 drivers/vme/vme.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/vme/vme.c b/drivers/vme/vme.c
index b398293980b6..bb4fed52f74d 100644
--- a/drivers/vme/vme.c
+++ b/drivers/vme/vme.c
@@ -73,7 +73,7 @@ static struct vme_bridge *find_bridge(struct vme_resource *resource)
 }
 
 /**
- * vme_free_consistent - Allocate contiguous memory.
+ * vme_alloc_consistent - Allocate contiguous memory.
  * @resource: Pointer to VME resource.
  * @size: Size of allocation required.
  * @dma: Pointer to variable to store physical address of allocation.
@@ -647,7 +647,7 @@ int vme_master_get(struct vme_resource *resource, int *enabled,
 EXPORT_SYMBOL(vme_master_get);
 
 /**
- * vme_master_write - Read data from VME space into a buffer.
+ * vme_master_read - Read data from VME space into a buffer.
  * @resource: Pointer to VME master resource.
  * @buf: Pointer to buffer where data should be transferred.
  * @count: Number of bytes to transfer.
-- 
2.26.2

[PATCH v3 34/56] fs: fix kernel-doc markups

[Mauro Carvalho Chehab]

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
@@ -456,23 +456,6 @@ static void d_lru_shrink_move(struct list_lru_one *lru, struct dentry *dentry,
 	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;
@@ -501,6 +484,23 @@ void __d_drop(struct dentry *dentry)
 }
 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);
@@ -989,6 +989,25 @@ struct dentry *d_find_any_alias(struct inode *inode)
 }
 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
@@ -1003,25 +1022,6 @@ EXPORT_SYMBOL(d_find_any_alias);
  * 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;
diff --git a/fs/inode.c b/fs/inode.c
index 9d78c37b00b8..aad3dcf2e259 100644
--- a/fs/inode.c
+++ b/fs/inode.c
@@ -1496,7 +1496,7 @@ struct inode *find_inode_rcu(struct super_block *sb, unsigned long hashval,
 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
  *
@@ -1778,7 +1778,7 @@ static int update_time(struct inode *inode, struct timespec64 *time, int flags)
 }
 
 /**
- *	touch_atime	-	update the access time
+ *	atime_needs_update	-	update the access time
  *	@path: the &struct path to update
  *	@inode: inode to update
  *
diff --git a/fs/seq_file.c b/fs/seq_file.c
index 31219c1db17d..f0b933179a74 100644
--- a/fs/seq_file.c
+++ b/fs/seq_file.c
@@ -653,7 +653,8 @@ void seq_puts(struct seq_file *m, const char *s)
 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
@@ -1028,7 +1029,7 @@ struct hlist_node *seq_hlist_next_rcu(void *v,
 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
diff --git a/fs/super.c b/fs/super.c
index a51c2083cd6b..3f7a4c10ef0a 100644
--- a/fs/super.c
+++ b/fs/super.c
@@ -1820,12 +1820,6 @@ int freeze_super(struct super_block *sb)
 }
 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;
@@ -1861,6 +1855,12 @@ static int thaw_super_locked(struct super_block *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);
-- 
2.26.2

[PATCH v3 35/56] jbd2: fix kernel-doc markups

[Mauro Carvalho Chehab]

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.

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 0c7c42bd530f..f71848367ab6 100644
--- a/fs/jbd2/journal.c
+++ b/fs/jbd2/journal.c
@@ -566,12 +566,14 @@ static int __jbd2_journal_force_commit(journal_t *journal)
 }
 
 /**
- * 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)
 {
@@ -582,7 +584,7 @@ int jbd2_journal_force_commit_nested(journal_t *journal)
 }
 
 /**
- * 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
@@ -1899,7 +1901,7 @@ static int load_superblock(journal_t *journal)
 
 
 /**
- * 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
@@ -1972,7 +1974,7 @@ int jbd2_journal_load(journal_t *journal)
 }
 
 /**
- * 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
@@ -2050,7 +2052,7 @@ int jbd2_journal_destroy(journal_t *journal)
 
 
 /**
- *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
@@ -2085,7 +2087,7 @@ int jbd2_journal_check_used_features(journal_t *journal, unsigned long compat,
 }
 
 /**
- * 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
@@ -2117,7 +2119,7 @@ int jbd2_journal_check_available_features(journal_t *journal, unsigned long comp
 }
 
 /**
- * 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
@@ -2201,7 +2203,7 @@ int jbd2_journal_set_features(journal_t *journal, unsigned long compat,
 }
 
 /*
- * 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
@@ -2230,7 +2232,7 @@ void jbd2_journal_clear_features(journal_t *journal, unsigned long compat,
 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.
@@ -2305,7 +2307,7 @@ int jbd2_journal_flush(journal_t *journal)
 }
 
 /**
- * int jbd2_journal_wipe() - Wipe journal contents
+ * jbd2_journal_wipe() - Wipe journal contents
  * @journal: Journal to act on.
  * @write: flag (see below)
  *
@@ -2346,7 +2348,7 @@ int jbd2_journal_wipe(journal_t *journal, int write)
 }
 
 /**
- * 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.
@@ -2437,7 +2439,7 @@ void jbd2_journal_abort(journal_t *journal, int errno)
 }
 
 /**
- * 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
@@ -2461,7 +2463,7 @@ int jbd2_journal_errno(journal_t *journal)
 }
 
 /**
- * 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
@@ -2481,7 +2483,7 @@ int jbd2_journal_clear_err(journal_t *journal)
 }
 
 /**
- * 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
diff --git a/fs/jbd2/transaction.c b/fs/jbd2/transaction.c
index 43985738aa86..4cf88191b025 100644
--- a/fs/jbd2/transaction.c
+++ b/fs/jbd2/transaction.c
@@ -517,7 +517,7 @@ 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
  *
@@ -564,7 +564,7 @@ void jbd2_journal_free_reserved(handle_t *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
@@ -618,7 +618,7 @@ int jbd2_journal_start_reserved(handle_t *handle, unsigned int type,
 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.
@@ -743,7 +743,7 @@ static void stop_this_handle(handle_t *handle)
 }
 
 /**
- * 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
@@ -813,7 +813,7 @@ int jbd2_journal_restart(handle_t *handle, int nblocks)
 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
@@ -872,7 +872,7 @@ void jbd2_journal_lock_updates(journal_t *journal)
 }
 
 /**
- * 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().
@@ -1180,7 +1180,8 @@ static bool jbd2_write_access_granted(handle_t *handle, struct buffer_head *bh,
 }
 
 /**
- * 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
  *
@@ -1224,7 +1225,7 @@ int jbd2_journal_get_write_access(handle_t *handle, struct buffer_head *bh)
  * 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.
  *
@@ -1304,7 +1305,7 @@ int jbd2_journal_get_create_access(handle_t *handle, struct buffer_head *bh)
 }
 
 /**
- * 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
@@ -1381,7 +1382,7 @@ int jbd2_journal_get_undo_access(handle_t *handle, struct buffer_head *bh)
 }
 
 /**
- * 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).
  *
@@ -1423,7 +1424,7 @@ void jbd2_buffer_abort_trigger(struct journal_head *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
  *
@@ -1591,7 +1592,7 @@ int jbd2_journal_dirty_metadata(handle_t *handle, struct buffer_head *bh)
 }
 
 /**
- * void jbd2_journal_forget() - bforget() for potentially-journaled buffers.
+ * jbd2_journal_forget() - bforget() for potentially-journaled buffers.
  * @handle: transaction handle
  * @bh:     bh to 'forget'
  *
@@ -1760,7 +1761,7 @@ int jbd2_journal_forget(handle_t *handle, struct buffer_head *bh)
 }
 
 /**
- * int jbd2_journal_stop() - complete a transaction
+ * jbd2_journal_stop() - complete a transaction
  * @handle: transaction to complete.
  *
  * All done for a particular handle.
@@ -2078,7 +2079,7 @@ __journal_try_to_free_buffer(journal_t *journal, struct buffer_head *bh)
 }
 
 /**
- * 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
  *
@@ -2409,7 +2410,7 @@ static int journal_unmap_buffer(journal_t *journal, struct buffer_head *bh,
 }
 
 /**
- * void jbd2_journal_invalidatepage()
+ * jbd2_journal_invalidatepage()
  * @journal: journal to use for flush...
  * @page:    page to flush
  * @offset:  start of the range to invalidate
diff --git a/include/linux/jbd2.h b/include/linux/jbd2.h
index 3c5f76ce88f1..17bed9684cba 100644
--- a/include/linux/jbd2.h
+++ b/include/linux/jbd2.h
@@ -397,7 +397,7 @@ static inline void jbd_unlock_bh_journal_head(struct buffer_head *bh)
 #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 {
-- 
2.26.2

[PATCH v3 36/56] locks: fix a typo at a kernel-doc markup

[Mauro Carvalho Chehab]

locks_delete_lock -> locks_delete_block

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

diff --git a/fs/locks.c b/fs/locks.c
index 1f84a03601fe..f3c3ce82a455 100644
--- a/fs/locks.c
+++ b/fs/locks.c
@@ -750,7 +750,7 @@ static void __locks_wake_up_blocks(struct file_lock *blocker)
 }
 
 /**
- *	locks_delete_lock - stop waiting for a file lock
+ *	locks_delete_block - stop waiting for a file lock
  *	@waiter: the lock which was waiting
  *
  *	lockd/nfsd need to disconnect the lock while working on it.
-- 
2.26.2

[PATCH v3 37/56] pstore/zone: fix a kernel-doc markup

[Mauro Carvalho Chehab]

The documented struct is psz_head and not psz_buffer.

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
@@ -23,7 +23,7 @@
 #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
-- 
2.26.2

[PATCH v3 38/56] clk: fix a kernel-doc markup

[Mauro Carvalho Chehab]

clk_get_duty_cycle -> clk_get_scaled_duty_cycle

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

diff --git a/include/linux/clk.h b/include/linux/clk.h
index 7fd6a1febcf4..5f8d5f4931c0 100644
--- a/include/linux/clk.h
+++ b/include/linux/clk.h
@@ -150,7 +150,7 @@ int clk_get_phase(struct clk *clk);
 int clk_set_duty_cycle(struct clk *clk, unsigned int num, unsigned int den);
 
 /**
- * clk_get_duty_cycle - return the duty cycle ratio of a clock signal
+ * clk_get_scaled_duty_cycle - return the duty cycle ratio of a clock signal
  * @clk: clock signal source
  * @scale: scaling factor to be applied to represent the ratio as an integer
  *
-- 
2.26.2

[PATCH v3 39/56] completion: fix kernel-doc markups

[Mauro Carvalho Chehab]

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
@@ -29,6 +29,14 @@ struct completion {
 };
 
 #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) {}
@@ -76,7 +84,7 @@ static inline void complete_release(struct completion *x) {}
 #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
-- 
2.26.2

[PATCH v3 40/56] firmware: stratix10-svc: fix kernel-doc markups

[Mauro Carvalho Chehab]

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.

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
@@ -6,7 +6,7 @@
 #ifndef __STRATIX10_SVC_CLIENT_H
 #define __STRATIX10_SVC_CLIENT_H
 
-/**
+/*
  * Service layer driver supports client names
  *
  * fpga: for FPGA configuration
@@ -15,7 +15,7 @@
 #define SVC_CLIENT_FPGA			"fpga"
 #define SVC_CLIENT_RSU			"rsu"
 
-/**
+/*
  * Status of the sent command, in bit number
  *
  * SVC_STATUS_OK:
@@ -50,7 +50,7 @@
 #define SVC_STATUS_ERROR		5
 #define SVC_STATUS_NO_SUPPORT		6
 
-/**
+/*
  * Flag bit for COMMAND_RECONFIG
  *
  * COMMAND_RECONFIG_FLAG_PARTIAL:
@@ -58,7 +58,7 @@
  */
 #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
@@ -218,7 +218,7 @@ void stratix10_svc_free_memory(struct stratix10_svc_chan *chan, void *kaddr);
 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
-- 
2.26.2

[PATCH v3 41/56] connector: fix a kernel-doc markup

[Mauro Carvalho Chehab]

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
@@ -99,7 +99,7 @@ void cn_del_callback(struct cb_id *id);
 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.
-- 
2.26.2

[PATCH v3 42/56] lib/crc7: fix a kernel-doc markup

[Mauro Carvalho Chehab]

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
@@ -51,7 +51,7 @@ const u8 crc7_be_syndrome_table[256] = {
 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
-- 
2.26.2

[PATCH v3 43/56] hrtimer: fix kernel-doc markups

[Mauro Carvalho Chehab]

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
@@ -447,6 +447,10 @@ static inline void hrtimer_restart(struct hrtimer *timer)
 /* 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);
@@ -458,7 +462,7 @@ 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
diff --git a/kernel/time/hrtimer.c b/kernel/time/hrtimer.c
index 3624b9b5835d..61c39ff68439 100644
--- a/kernel/time/hrtimer.c
+++ b/kernel/time/hrtimer.c
@@ -1289,7 +1289,7 @@ int hrtimer_cancel(struct hrtimer *timer)
 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
  */
-- 
2.26.2

[PATCH v3 44/56] genirq: fix kernel-doc markups

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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
@@ -61,7 +61,7 @@ int irq_set_chip(unsigned int irq, struct irq_chip *chip)
 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
  */
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
@@ -269,7 +269,7 @@ irq_gc_init_mask_cache(struct irq_chip_generic *gc, enum irq_gc_flags flags)
 }
 
 /**
- * __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
-- 
2.26.2

[PATCH v3 45/56] iio: fix a kernel-doc markup

[Mauro Carvalho Chehab]

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/iio/trigger.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/iio/trigger.h b/include/linux/iio/trigger.h
index cad8325903f9..f930c4ccf378 100644
--- a/include/linux/iio/trigger.h
+++ b/include/linux/iio/trigger.h
@@ -97,7 +97,7 @@ static inline struct iio_trigger *iio_trigger_get(struct iio_trigger *trig)
 }
 
 /**
- * iio_device_set_drvdata() - Set trigger driver data
+ * iio_trigger_set_drvdata() - Set trigger driver data
  * @trig: IIO trigger structure
  * @data: Driver specific data
  *
-- 
2.26.2

[PATCH v3 46/56] list: fix a typo at the kernel-doc markup

[Mauro Carvalho Chehab]

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 a18c87b63376..f72a7a778722 100644
--- a/include/linux/list.h
+++ b/include/linux/list.h
@@ -901,7 +901,7 @@ static inline void hlist_add_before(struct hlist_node *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
  */
-- 
2.26.2

[PATCH v3 47/56] memblock: fix kernel-doc markups

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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
@@ -272,7 +272,7 @@ 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
@@ -292,7 +292,7 @@ void __next_mem_pfn_range_in_zone(u64 *idx, struct zone *zone,
 	     __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
-- 
2.26.2

[PATCH v3 48/56] sound: fix kernel-doc markups

[Mauro Carvalho Chehab]

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

There is a common comment marked, instead, with kernel-doc
notation.

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 include/sound/core.h                  | 3 ++-
 include/sound/pcm.h                   | 4 ++--
 include/uapi/sound/compress_offload.h | 2 +-
 sound/core/control.c                  | 4 ++--
 sound/core/pcm_dmaengine.c            | 3 ++-
 sound/core/pcm_lib.c                  | 2 +-
 sound/core/pcm_native.c               | 4 ++--
 sound/soc/soc-core.c                  | 2 +-
 sound/soc/soc-dapm.c                  | 2 +-
 9 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/include/sound/core.h b/include/sound/core.h
index 381a010a1bd4..0462c577d7a3 100644
--- a/include/sound/core.h
+++ b/include/sound/core.h
@@ -332,7 +332,8 @@ void __snd_printk(unsigned int level, const char *file, int line,
 #define snd_BUG()		WARN(1, "BUG?\n")
 
 /**
- * Suppress high rates of output when CONFIG_SND_DEBUG is enabled.
+ * snd_printd_ratelimit - Suppress high rates of output when
+ * 			  CONFIG_SND_DEBUG is enabled.
  */
 #define snd_printd_ratelimit() printk_ratelimit()
 
diff --git a/include/sound/pcm.h b/include/sound/pcm.h
index 2ba5df2c9e23..2336bf9243e1 100644
--- a/include/sound/pcm.h
+++ b/include/sound/pcm.h
@@ -1284,8 +1284,8 @@ snd_pcm_sgbuf_get_ptr(struct snd_pcm_substream *substream, unsigned int ofs)
 }
 
 /**
- * snd_pcm_sgbuf_chunk_size - Compute the max size that fits within the contig.
- * page from the given size
+ * snd_pcm_sgbuf_get_chunk_size - Compute the max size that fits within the
+ * contig. page from the given size
  * @substream: PCM substream
  * @ofs: byte offset
  * @size: byte size to examine
diff --git a/include/uapi/sound/compress_offload.h b/include/uapi/sound/compress_offload.h
index 7184265c0b0d..9555f31c8425 100644
--- a/include/uapi/sound/compress_offload.h
+++ b/include/uapi/sound/compress_offload.h
@@ -144,7 +144,7 @@ struct snd_compr_metadata {
 	 __u32 value[8];
 } __attribute__((packed, aligned(4)));
 
-/**
+/*
  * compress path ioctl definitions
  * SNDRV_COMPRESS_GET_CAPS: Query capability of DSP
  * SNDRV_COMPRESS_GET_CODEC_CAPS: Query capability of a codec
diff --git a/sound/core/control.c b/sound/core/control.c
index 421ddc76f264..4373de42a5a0 100644
--- a/sound/core/control.c
+++ b/sound/core/control.c
@@ -1925,8 +1925,8 @@ EXPORT_SYMBOL(snd_ctl_unregister_ioctl);
 
 #ifdef CONFIG_COMPAT
 /**
- * snd_ctl_unregister_ioctl - de-register the device-specific compat 32bit
- * control-ioctls
+ * snd_ctl_unregister_ioctl_compat - de-register the device-specific compat
+ * 32bit control-ioctls
  * @fcn: ioctl callback function to unregister
  */
 int snd_ctl_unregister_ioctl_compat(snd_kctl_ioctl_func_t fcn)
diff --git a/sound/core/pcm_dmaengine.c b/sound/core/pcm_dmaengine.c
index 4d059ff2b2e4..4d0e8fe535a1 100644
--- a/sound/core/pcm_dmaengine.c
+++ b/sound/core/pcm_dmaengine.c
@@ -356,7 +356,8 @@ int snd_dmaengine_pcm_close(struct snd_pcm_substream *substream)
 EXPORT_SYMBOL_GPL(snd_dmaengine_pcm_close);
 
 /**
- * snd_dmaengine_pcm_release_chan_close - Close a dmaengine based PCM substream and release channel
+ * snd_dmaengine_pcm_close_release_chan - Close a dmaengine based PCM
+ *					  substream and release channel
  * @substream: PCM substream
  *
  * Releases the DMA channel associated with the PCM substream.
diff --git a/sound/core/pcm_lib.c b/sound/core/pcm_lib.c
index d531e1bc2b81..bda3514c7b2d 100644
--- a/sound/core/pcm_lib.c
+++ b/sound/core/pcm_lib.c
@@ -490,7 +490,7 @@ void snd_pcm_set_ops(struct snd_pcm *pcm, int direction,
 EXPORT_SYMBOL(snd_pcm_set_ops);
 
 /**
- * snd_pcm_sync - set the PCM sync id
+ * snd_pcm_set_sync - set the PCM sync id
  * @substream: the pcm substream
  *
  * Sets the PCM sync identifier for the card.
diff --git a/sound/core/pcm_native.c b/sound/core/pcm_native.c
index 9e0b2d73faf6..47b155a49226 100644
--- a/sound/core/pcm_native.c
+++ b/sound/core/pcm_native.c
@@ -112,7 +112,7 @@ void snd_pcm_stream_lock(struct snd_pcm_substream *substream)
 EXPORT_SYMBOL_GPL(snd_pcm_stream_lock);
 
 /**
- * snd_pcm_stream_lock - Unlock the PCM stream
+ * snd_pcm_stream_unlock - Unlock the PCM stream
  * @substream: PCM substream
  *
  * This unlocks the PCM stream that has been locked via snd_pcm_stream_lock().
@@ -595,7 +595,7 @@ static void snd_pcm_sync_stop(struct snd_pcm_substream *substream)
 }
 
 /**
- * snd_pcm_hw_param_choose - choose a configuration defined by @params
+ * snd_pcm_hw_params_choose - choose a configuration defined by @params
  * @pcm: PCM instance
  * @params: the hw_params instance
  *
diff --git a/sound/soc/soc-core.c b/sound/soc/soc-core.c
index ea3986a46c12..05a085f6dc7c 100644
--- a/sound/soc/soc-core.c
+++ b/sound/soc/soc-core.c
@@ -2341,7 +2341,7 @@ struct snd_soc_dai *snd_soc_register_dai(struct snd_soc_component *component,
 }
 
 /**
- * snd_soc_unregister_dai - Unregister DAIs from the ASoC core
+ * snd_soc_unregister_dais - Unregister DAIs from the ASoC core
  *
  * @component: The component for which the DAIs should be unregistered
  */
diff --git a/sound/soc/soc-dapm.c b/sound/soc/soc-dapm.c
index 980f2c330b87..7f87b449f950 100644
--- a/sound/soc/soc-dapm.c
+++ b/sound/soc/soc-dapm.c
@@ -1276,7 +1276,7 @@ static int is_connected_input_ep(struct snd_soc_dapm_widget *widget,
 }
 
 /**
- * snd_soc_dapm_get_connected_widgets - query audio path and it's widgets.
+ * snd_soc_dapm_dai_get_connected_widgets - query audio path and it's widgets.
  * @dai: the soc DAI.
  * @stream: stream direction.
  * @list: list of active widgets for this stream.
-- 
2.26.2

[PATCH v3 49/56] refcount.h: fix a kernel-doc markup

[Mauro Carvalho Chehab]

The documented typedef just after the kernel-doc markup
is named "refcount_struct".

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

diff --git a/include/linux/refcount.h b/include/linux/refcount.h
index 497990c69b0b..8f431b0e69e4 100644
--- a/include/linux/refcount.h
+++ b/include/linux/refcount.h
@@ -101,7 +101,7 @@
 struct mutex;
 
 /**
- * struct refcount_t - variant of atomic_t specialized for reference counts
+ * struct refcount_struct - variant of atomic_t specialized for reference counts
  * @refs: atomic_t counter field
  *
  * The counter saturates at REFCOUNT_SATURATED and will not move once
-- 
2.26.2

[PATCH v3 50/56] w1: fix a kernel-doc markup

[Mauro Carvalho Chehab]

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
@@ -280,7 +280,7 @@ 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
-- 
2.26.2

[PATCH v3 51/56] audit: fix a kernel-doc markup

[Mauro Carvalho Chehab]

typo:
	kauditd_print_skb -> kauditd_printk_skb

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

diff --git a/kernel/audit.c b/kernel/audit.c
index 68cee3bc8cfe..0be42cac086b 100644
--- a/kernel/audit.c
+++ b/kernel/audit.c
@@ -523,7 +523,7 @@ static int auditd_set(struct pid *pid, u32 portid, struct net *net)
 }
 
 /**
- * kauditd_print_skb - Print the audit record to the ring buffer
+ * kauditd_printk_skb - Print the audit record to the ring buffer
  * @skb: audit record
  *
  * Whatever the reason, this packet may not make it to the auditd connection
-- 
2.26.2

[PATCH v3 52/56] resource: fix kernel-doc markups

[Mauro Carvalho Chehab]

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
@@ -320,9 +320,8 @@ int release_resource(struct resource *old)
 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
@@ -337,6 +336,9 @@ EXPORT_SYMBOL(release_resource);
  * @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,
@@ -416,11 +418,9 @@ static int __walk_iomem_res_desc(resource_size_t start, resource_size_t end,
 }
 
 /**
- * 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
@@ -428,6 +428,10 @@ static int __walk_iomem_res_desc(resource_size_t start, resource_size_t end,
  * @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.
  */
@@ -1372,9 +1376,9 @@ static bool system_ram_resources_mergeable(struct resource *r1,
 	       !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
-- 
2.26.2

[PATCH v3 53/56] shed: fix kernel-doc markup

[Mauro Carvalho Chehab]

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 |  3 ++-
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/kernel/sched/core.c b/kernel/sched/core.c
index 8160ab5263f8..f7189247f007 100644
--- a/kernel/sched/core.c
+++ b/kernel/sched/core.c
@@ -6076,14 +6076,6 @@ SYSCALL_DEFINE3(sched_getaffinity, pid_t, pid, unsigned int, len,
 	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;
@@ -6105,6 +6097,14 @@ static void do_sched_yield(void)
 	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();
diff --git a/kernel/sched/fair.c b/kernel/sched/fair.c
index aa4c6227cd6d..94386fcfafcf 100644
--- a/kernel/sched/fair.c
+++ b/kernel/sched/fair.c
@@ -6287,7 +6287,8 @@ static int select_idle_sibling(struct task_struct *p, int prev, int target)
 }
 
 /**
- * Amount of capacity of a CPU that is (estimated to be) used by CFS tasks
+ * cpu_util - Amount of capacity of a CPU that is (estimated to be)
+ *	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
-- 
2.26.2

[PATCH v3 54/56] mm: fix kernel-doc markups

[Mauro Carvalho Chehab]

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.

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 102877ed77a4..3dc7c0fe9231 100644
--- a/mm/gup.c
+++ b/mm/gup.c
@@ -1926,7 +1926,19 @@ long get_user_pages(unsigned long start, unsigned long nr_pages,
 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()
@@ -1942,16 +1954,6 @@ EXPORT_SYMBOL(get_user_pages);
  *      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().
diff --git a/mm/page_alloc.c b/mm/page_alloc.c
index 23f5066bd4a5..c94094ce1621 100644
--- a/mm/page_alloc.c
+++ b/mm/page_alloc.c
@@ -495,14 +495,6 @@ static inline int pfn_to_bitidx(struct page *page, unsigned long pfn)
 	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,
@@ -521,6 +513,14 @@ unsigned long __get_pfnblock_flags_mask(struct page *page,
 	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)
 {
diff --git a/mm/truncate.c b/mm/truncate.c
index 18cec39a9f53..58fa634cf4f8 100644
--- a/mm/truncate.c
+++ b/mm/truncate.c
@@ -637,9 +637,15 @@ unsigned long invalidate_mapping_pages(struct address_space *mapping,
 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 with
+ * invalidate_mapping_pages(), except that it accounts for pages tat are
+ * likely on a pagevec and count them in @nr_pagevec, which will 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)
-- 
2.26.2

[PATCH v3 55/56] selftests: kselftest_harness.h: partially fix kernel-doc markups

[Mauro Carvalho Chehab]

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 | 66 ++++++++++-----------
 1 file changed, 33 insertions(+), 33 deletions(-)

diff --git a/tools/testing/selftests/kselftest_harness.h b/tools/testing/selftests/kselftest_harness.h
index f19804df244c..665d04f3b802 100644
--- a/tools/testing/selftests/kselftest_harness.h
+++ b/tools/testing/selftests/kselftest_harness.h
@@ -79,7 +79,7 @@
 #endif
 
 /**
- * TH_LOG(fmt, ...)
+ * TH_LOG()
  *
  * @fmt: format string
  * @...: optional arguments
@@ -113,7 +113,7 @@
 			__FILE__, __LINE__, _metadata->name, ##__VA_ARGS__)
 
 /**
- * SKIP(statement, fmt, ...)
+ * SKIP()
  *
  * @statement: statement to run after reporting SKIP
  * @fmt: format string
@@ -136,7 +136,7 @@
 } 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
@@ -155,7 +155,7 @@
 #define TEST(test_name) __TEST_IMPL(test_name, -1)
 
 /**
- * TEST_SIGNAL(test_name, signal)
+ * TEST_SIGNAL()
  *
  * @test_name: test name
  * @signal: signal number
@@ -195,7 +195,7 @@
 		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
@@ -212,7 +212,7 @@
 #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
@@ -239,7 +239,7 @@
 	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
@@ -265,7 +265,7 @@
 			__attribute__((unused)) *variant)
 
 /**
- * FIXTURE_TEARDOWN(fixture_name)
+ * FIXTURE_TEARDOWN()
  * *_metadata* is included so that EXPECT_* and ASSERT_* work correctly.
  *
  * @fixture_name: fixture name
@@ -286,7 +286,7 @@
 		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
@@ -305,7 +305,7 @@
 #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
@@ -339,7 +339,7 @@
 		_##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
@@ -432,7 +432,7 @@
  */
 
 /**
- * ASSERT_EQ(expected, seen)
+ * ASSERT_EQ()
  *
  * @expected: expected value
  * @seen: measured value
@@ -443,7 +443,7 @@
 	__EXPECT(expected, #expected, seen, #seen, ==, 1)
 
 /**
- * ASSERT_NE(expected, seen)
+ * ASSERT_NE()
  *
  * @expected: expected value
  * @seen: measured value
@@ -454,7 +454,7 @@
 	__EXPECT(expected, #expected, seen, #seen, !=, 1)
 
 /**
- * ASSERT_LT(expected, seen)
+ * ASSERT_LT()
  *
  * @expected: expected value
  * @seen: measured value
@@ -465,7 +465,7 @@
 	__EXPECT(expected, #expected, seen, #seen, <, 1)
 
 /**
- * ASSERT_LE(expected, seen)
+ * ASSERT_LE()
  *
  * @expected: expected value
  * @seen: measured value
@@ -476,7 +476,7 @@
 	__EXPECT(expected, #expected, seen, #seen, <=, 1)
 
 /**
- * ASSERT_GT(expected, seen)
+ * ASSERT_GT()
  *
  * @expected: expected value
  * @seen: measured value
@@ -487,7 +487,7 @@
 	__EXPECT(expected, #expected, seen, #seen, >, 1)
 
 /**
- * ASSERT_GE(expected, seen)
+ * ASSERT_GE()
  *
  * @expected: expected value
  * @seen: measured value
@@ -498,7 +498,7 @@
 	__EXPECT(expected, #expected, seen, #seen, >=, 1)
 
 /**
- * ASSERT_NULL(seen)
+ * ASSERT_NULL()
  *
  * @seen: measured value
  *
@@ -508,7 +508,7 @@
 	__EXPECT(NULL, "NULL", seen, #seen, ==, 1)
 
 /**
- * ASSERT_TRUE(seen)
+ * ASSERT_TRUE()
  *
  * @seen: measured value
  *
@@ -518,7 +518,7 @@
 	__EXPECT(0, "0", seen, #seen, !=, 1)
 
 /**
- * ASSERT_FALSE(seen)
+ * ASSERT_FALSE()
  *
  * @seen: measured value
  *
@@ -528,7 +528,7 @@
 	__EXPECT(0, "0", seen, #seen, ==, 1)
 
 /**
- * ASSERT_STREQ(expected, seen)
+ * ASSERT_STREQ()
  *
  * @expected: expected value
  * @seen: measured value
@@ -539,7 +539,7 @@
 	__EXPECT_STR(expected, seen, ==, 1)
 
 /**
- * ASSERT_STRNE(expected, seen)
+ * ASSERT_STRNE()
  *
  * @expected: expected value
  * @seen: measured value
@@ -550,7 +550,7 @@
 	__EXPECT_STR(expected, seen, !=, 1)
 
 /**
- * EXPECT_EQ(expected, seen)
+ * EXPECT_EQ()
  *
  * @expected: expected value
  * @seen: measured value
@@ -561,7 +561,7 @@
 	__EXPECT(expected, #expected, seen, #seen, ==, 0)
 
 /**
- * EXPECT_NE(expected, seen)
+ * EXPECT_NE()
  *
  * @expected: expected value
  * @seen: measured value
@@ -572,7 +572,7 @@
 	__EXPECT(expected, #expected, seen, #seen, !=, 0)
 
 /**
- * EXPECT_LT(expected, seen)
+ * EXPECT_LT()
  *
  * @expected: expected value
  * @seen: measured value
@@ -583,7 +583,7 @@
 	__EXPECT(expected, #expected, seen, #seen, <, 0)
 
 /**
- * EXPECT_LE(expected, seen)
+ * EXPECT_LE()
  *
  * @expected: expected value
  * @seen: measured value
@@ -594,7 +594,7 @@
 	__EXPECT(expected, #expected, seen, #seen, <=, 0)
 
 /**
- * EXPECT_GT(expected, seen)
+ * EXPECT_GT()
  *
  * @expected: expected value
  * @seen: measured value
@@ -605,7 +605,7 @@
 	__EXPECT(expected, #expected, seen, #seen, >, 0)
 
 /**
- * EXPECT_GE(expected, seen)
+ * EXPECT_GE()
  *
  * @expected: expected value
  * @seen: measured value
@@ -616,7 +616,7 @@
 	__EXPECT(expected, #expected, seen, #seen, >=, 0)
 
 /**
- * EXPECT_NULL(seen)
+ * EXPECT_NULL()
  *
  * @seen: measured value
  *
@@ -626,7 +626,7 @@
 	__EXPECT(NULL, "NULL", seen, #seen, ==, 0)
 
 /**
- * EXPECT_TRUE(seen)
+ * EXPECT_TRUE()
  *
  * @seen: measured value
  *
@@ -636,7 +636,7 @@
 	__EXPECT(0, "0", seen, #seen, !=, 0)
 
 /**
- * EXPECT_FALSE(seen)
+ * EXPECT_FALSE()
  *
  * @seen: measured value
  *
@@ -646,7 +646,7 @@
 	__EXPECT(0, "0", seen, #seen, ==, 0)
 
 /**
- * EXPECT_STREQ(expected, seen)
+ * EXPECT_STREQ()
  *
  * @expected: expected value
  * @seen: measured value
@@ -657,7 +657,7 @@
 	__EXPECT_STR(expected, seen, ==, 0)
 
 /**
- * EXPECT_STRNE(expected, seen)
+ * EXPECT_STRNE()
  *
  * @expected: expected value
  * @seen: measured value
-- 
2.26.2

[PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names

[Mauro Carvalho Chehab]

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 311d213ee74d..1371cd45f78b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -382,6 +382,9 @@ my $inline_doc_state;
 # '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*';
@@ -1203,6 +1206,11 @@ sub dump_struct($$) {
 	$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;
@@ -1391,6 +1399,11 @@ sub dump_enum($$) {
     }
 
     if ($declaration_name) {
+	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+$//;
@@ -1446,6 +1459,11 @@ sub dump_typedef($$) {
 	$declaration_name = $2;
 	my $args = $3;
 
+	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,
@@ -1472,6 +1490,11 @@ sub dump_typedef($$) {
     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,
@@ -1791,6 +1814,11 @@ sub dump_function($$) {
 	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);
 
@@ -1873,6 +1901,7 @@ sub tracepoint_munge($) {
 			     "$prototype\n";
 	} else {
 		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
+		$identifier = "trace_$identifier";
 	}
 }
 
@@ -2036,7 +2065,6 @@ sub process_normal() {
 #
 sub process_name($$) {
     my $file = shift;
-    my $identifier;
     my $descr;
 
     if (/$doc_block/o) {
@@ -2049,12 +2077,19 @@ sub process_name($$) {
 	} 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
@@ -2062,7 +2097,7 @@ sub process_name($$) {
 	$contents = "";
 	$section = $section_default;
 	$new_start_line = $. + 1;
-	if (/-(.*)/) {
+	if (/[-:](.*)/) {
 	    # strip leading/trailing/multiple spaces
 	    $descr= $1;
 	    $descr =~ s/^\s*//;
@@ -2080,20 +2115,15 @@ sub process_name($$) {
 	    ++$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 $.",
-- 
2.26.2

Re: [PATCH v3 03/56] amdgpu: fix a few kernel-doc markup issues

[Christian König]

Am 23.10.20 um 18:32 schrieb Mauro Carvalho Chehab:
> A kernel-doc markup can't be mixed with a random comment,
> as it causes parsing problems.
>
> While here, change an invalid kernel-doc markup into
> a common comment.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Acked-by: Christian König <christian.koenig@amd.com>

> ---
>   drivers/gpu/drm/amd/amdgpu/amdgpu_device.c | 8 +++++---
>   1 file changed, 5 insertions(+), 3 deletions(-)
>
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
> index f8785bdec79c..1d4b54950528 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
> @@ -239,9 +239,11 @@ bool amdgpu_device_supports_baco(struct drm_device *dev)
>   	return amdgpu_asic_supports_baco(adev);
>   }
>   
> +/*
> + * VRAM access helper functions
> + */
> +
>   /**
> - * VRAM access helper functions.
> - *
>    * amdgpu_device_vram_access - read/write a buffer in vram
>    *
>    * @adev: amdgpu_device pointer
> @@ -4497,7 +4499,7 @@ int amdgpu_device_gpu_recover(struct amdgpu_device *adev,
>   	bool need_emergency_restart = false;
>   	bool audio_suspended = false;
>   
> -	/**
> +	/*
>   	 * Special case: RAS triggered and full reset isn't supported
>   	 */
>   	need_emergency_restart = amdgpu_ras_need_emergency_restart(adev);

Re: [PATCH v3 11/56] drm/amdgpu: fix some kernel-doc markups

[Christian König]

Am 23.10.20 um 18:32 schrieb Mauro Carvalho Chehab:
> Some functions have different names between their prototypes
> and the kernel-doc markup.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Acked-by: Christian König <christian.koenig@amd.com>

> ---
>   drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c       | 2 +-
>   drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 2 +-
>   include/uapi/drm/amdgpu_drm.h                | 2 +-
>   3 files changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> index df110afa97bf..a5f73a267fe5 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> @@ -2166,7 +2166,7 @@ struct amdgpu_bo_va *amdgpu_vm_bo_add(struct amdgpu_device *adev,
>   
>   
>   /**
> - * amdgpu_vm_bo_insert_mapping - insert a new mapping
> + * amdgpu_vm_bo_insert_map - insert a new mapping
>    *
>    * @adev: amdgpu_device pointer
>    * @bo_va: bo_va to store the address
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> index 0c6b7c5ecfec..795bad307497 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> @@ -528,7 +528,7 @@ int amdgpu_vram_mgr_alloc_sgt(struct amdgpu_device *adev,
>   }
>   
>   /**
> - * amdgpu_vram_mgr_alloc_sgt - allocate and fill a sg table
> + * amdgpu_vram_mgr_free_sgt - allocate and fill a sg table
>    *
>    * @adev: amdgpu device pointer
>    * @sgt: sg table to free
> diff --git a/include/uapi/drm/amdgpu_drm.h b/include/uapi/drm/amdgpu_drm.h
> index c5ff2b275fcd..791a1d597d2a 100644
> --- a/include/uapi/drm/amdgpu_drm.h
> +++ b/include/uapi/drm/amdgpu_drm.h
> @@ -667,7 +667,7 @@ struct drm_amdgpu_cs_chunk_data {
>   	};
>   };
>   
> -/**
> +/*
>    *  Query h/w info: Flag that this is integrated (a.h.a. fusion) GPU
>    *
>    */

Re: [PATCH v3 35/56] jbd2: fix kernel-doc markups

[Jan Kara]

On Fri 23-10-20 18:33:22, 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.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Thanks for the patch. It looks good. You can add:

Reviewed-by: Jan Kara <jack@suse.cz>

								Honza

> ---
>  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 0c7c42bd530f..f71848367ab6 100644
> --- a/fs/jbd2/journal.c
> +++ b/fs/jbd2/journal.c
> @@ -566,12 +566,14 @@ static int __jbd2_journal_force_commit(journal_t *journal)
>  }
>  
>  /**
> - * 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)
>  {
> @@ -582,7 +584,7 @@ int jbd2_journal_force_commit_nested(journal_t *journal)
>  }
>  
>  /**
> - * 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
> @@ -1899,7 +1901,7 @@ static int load_superblock(journal_t *journal)
>  
>  
>  /**
> - * 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
> @@ -1972,7 +1974,7 @@ int jbd2_journal_load(journal_t *journal)
>  }
>  
>  /**
> - * 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
> @@ -2050,7 +2052,7 @@ int jbd2_journal_destroy(journal_t *journal)
>  
>  
>  /**
> - *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
> @@ -2085,7 +2087,7 @@ int jbd2_journal_check_used_features(journal_t *journal, unsigned long compat,
>  }
>  
>  /**
> - * 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
> @@ -2117,7 +2119,7 @@ int jbd2_journal_check_available_features(journal_t *journal, unsigned long comp
>  }
>  
>  /**
> - * 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
> @@ -2201,7 +2203,7 @@ int jbd2_journal_set_features(journal_t *journal, unsigned long compat,
>  }
>  
>  /*
> - * 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
> @@ -2230,7 +2232,7 @@ void jbd2_journal_clear_features(journal_t *journal, unsigned long compat,
>  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.
> @@ -2305,7 +2307,7 @@ int jbd2_journal_flush(journal_t *journal)
>  }
>  
>  /**
> - * int jbd2_journal_wipe() - Wipe journal contents
> + * jbd2_journal_wipe() - Wipe journal contents
>   * @journal: Journal to act on.
>   * @write: flag (see below)
>   *
> @@ -2346,7 +2348,7 @@ int jbd2_journal_wipe(journal_t *journal, int write)
>  }
>  
>  /**
> - * 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.
> @@ -2437,7 +2439,7 @@ void jbd2_journal_abort(journal_t *journal, int errno)
>  }
>  
>  /**
> - * 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
> @@ -2461,7 +2463,7 @@ int jbd2_journal_errno(journal_t *journal)
>  }
>  
>  /**
> - * 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
> @@ -2481,7 +2483,7 @@ int jbd2_journal_clear_err(journal_t *journal)
>  }
>  
>  /**
> - * 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
> diff --git a/fs/jbd2/transaction.c b/fs/jbd2/transaction.c
> index 43985738aa86..4cf88191b025 100644
> --- a/fs/jbd2/transaction.c
> +++ b/fs/jbd2/transaction.c
> @@ -517,7 +517,7 @@ 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
>   *
> @@ -564,7 +564,7 @@ void jbd2_journal_free_reserved(handle_t *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
> @@ -618,7 +618,7 @@ int jbd2_journal_start_reserved(handle_t *handle, unsigned int type,
>  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.
> @@ -743,7 +743,7 @@ static void stop_this_handle(handle_t *handle)
>  }
>  
>  /**
> - * 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
> @@ -813,7 +813,7 @@ int jbd2_journal_restart(handle_t *handle, int nblocks)
>  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
> @@ -872,7 +872,7 @@ void jbd2_journal_lock_updates(journal_t *journal)
>  }
>  
>  /**
> - * 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().
> @@ -1180,7 +1180,8 @@ static bool jbd2_write_access_granted(handle_t *handle, struct buffer_head *bh,
>  }
>  
>  /**
> - * 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
>   *
> @@ -1224,7 +1225,7 @@ int jbd2_journal_get_write_access(handle_t *handle, struct buffer_head *bh)
>   * 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.
>   *
> @@ -1304,7 +1305,7 @@ int jbd2_journal_get_create_access(handle_t *handle, struct buffer_head *bh)
>  }
>  
>  /**
> - * 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
> @@ -1381,7 +1382,7 @@ int jbd2_journal_get_undo_access(handle_t *handle, struct buffer_head *bh)
>  }
>  
>  /**
> - * 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).
>   *
> @@ -1423,7 +1424,7 @@ void jbd2_buffer_abort_trigger(struct journal_head *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
>   *
> @@ -1591,7 +1592,7 @@ int jbd2_journal_dirty_metadata(handle_t *handle, struct buffer_head *bh)
>  }
>  
>  /**
> - * void jbd2_journal_forget() - bforget() for potentially-journaled buffers.
> + * jbd2_journal_forget() - bforget() for potentially-journaled buffers.
>   * @handle: transaction handle
>   * @bh:     bh to 'forget'
>   *
> @@ -1760,7 +1761,7 @@ int jbd2_journal_forget(handle_t *handle, struct buffer_head *bh)
>  }
>  
>  /**
> - * int jbd2_journal_stop() - complete a transaction
> + * jbd2_journal_stop() - complete a transaction
>   * @handle: transaction to complete.
>   *
>   * All done for a particular handle.
> @@ -2078,7 +2079,7 @@ __journal_try_to_free_buffer(journal_t *journal, struct buffer_head *bh)
>  }
>  
>  /**
> - * 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
>   *
> @@ -2409,7 +2410,7 @@ static int journal_unmap_buffer(journal_t *journal, struct buffer_head *bh,
>  }
>  
>  /**
> - * void jbd2_journal_invalidatepage()
> + * jbd2_journal_invalidatepage()
>   * @journal: journal to use for flush...
>   * @page:    page to flush
>   * @offset:  start of the range to invalidate
> diff --git a/include/linux/jbd2.h b/include/linux/jbd2.h
> index 3c5f76ce88f1..17bed9684cba 100644
> --- a/include/linux/jbd2.h
> +++ b/include/linux/jbd2.h
> @@ -397,7 +397,7 @@ static inline void jbd_unlock_bh_journal_head(struct buffer_head *bh)
>  #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 {
> -- 
> 2.26.2
> 
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

Re: [PATCH v3 01/56] scripts: kernel-doc: fix typedef parsing

[Jonathan Corbet]

On Fri, 23 Oct 2020 18:32:48 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> The include/linux/genalloc.h file defined this typedef:
> 
> 	typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
> 
> Because it has a type composite of two words (unsigned long),
> the parser gets the typedef name wrong:
> 
> .. c:macro:: long
> 
>    **Typedef**: Allocation callback function type definition
> 
> Fix the regex in order to accept composite types when
> defining a typedef for a function pointer.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  scripts/kernel-doc | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 99cd8418ff8a..311d213ee74d 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1438,7 +1438,7 @@ sub dump_typedef($$) {
>      $x =~ s@/\*.*?\*/@@gos;	# strip comments.
>  
>      # Parse function prototypes
> -    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> +    if ($x =~ /typedef\s+(\w+\s*){1,}\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||

I sure wish we could find a way to make all these regexes more
understandable and maintainable.  Reviewing a change like this is ... fun.

Anyway, it seems to work, but it does now include trailing whitespace in
the type portion.  So, for example, from include/linux/xarray.h:

  typedef void (*xa_update_node_t)(struct xa_node *node);

The type is parsed as "void " where it was "void" before.  The only ill
effect I can see is that some non-breaking spaces get inserted into the
HTML output, but perhaps it's worth stripping off that trailing space
anyway?

Thanks,

jon

Re: [PATCH v3 15/56] media: fix kernel-doc markups

[Sakari Ailus]

Thanks, Mauro!

On Fri, Oct 23, 2020 at 06:33:02PM +0200, Mauro Carvalho Chehab wrote:
> Some identifiers have different names between their prototypes
> and the kernel-doc markup. Seome seems to be due to cut-and-paste
> related issues.
> 
> 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>

On IPU3 and V4L2 bits:

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>

-- 
Regards,

Sakari Ailus

Re: [PATCH v3 55/56] selftests: kselftest_harness.h: partially fix kernel-doc markups

[Kees Cook]

On Fri, Oct 23, 2020 at 06:33:42PM +0200, Mauro Carvalho Chehab wrote:
> 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 | 66 ++++++++++-----------
>  1 file changed, 33 insertions(+), 33 deletions(-)
> 
> diff --git a/tools/testing/selftests/kselftest_harness.h b/tools/testing/selftests/kselftest_harness.h
> index f19804df244c..665d04f3b802 100644
> --- a/tools/testing/selftests/kselftest_harness.h
> +++ b/tools/testing/selftests/kselftest_harness.h
> @@ -79,7 +79,7 @@
>  #endif
>  
>  /**
> - * TH_LOG(fmt, ...)
> + * TH_LOG()
>   *
>   * @fmt: format string
>   * @...: optional arguments

Hmmm. Yeah, this does need fixing, but I don't want to lose the
"examples". Some have stuff like this before the description:

 * .. code-block:: c
 *
 *     TH_LOG(format, ...)

which retains it, but many don't. Can you add the code-block:: c
sections where they're missing so this doesn't lose the syntax hints
when just looking at the header file alone.

-Kees

> @@ -113,7 +113,7 @@
>  			__FILE__, __LINE__, _metadata->name, ##__VA_ARGS__)
>  
>  /**
> - * SKIP(statement, fmt, ...)
> + * SKIP()
>   *
>   * @statement: statement to run after reporting SKIP
>   * @fmt: format string
> @@ -136,7 +136,7 @@
>  } 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
> @@ -155,7 +155,7 @@
>  #define TEST(test_name) __TEST_IMPL(test_name, -1)
>  
>  /**
> - * TEST_SIGNAL(test_name, signal)
> + * TEST_SIGNAL()
>   *
>   * @test_name: test name
>   * @signal: signal number
> @@ -195,7 +195,7 @@
>  		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
> @@ -212,7 +212,7 @@
>  #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
> @@ -239,7 +239,7 @@
>  	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
> @@ -265,7 +265,7 @@
>  			__attribute__((unused)) *variant)
>  
>  /**
> - * FIXTURE_TEARDOWN(fixture_name)
> + * FIXTURE_TEARDOWN()
>   * *_metadata* is included so that EXPECT_* and ASSERT_* work correctly.
>   *
>   * @fixture_name: fixture name
> @@ -286,7 +286,7 @@
>  		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
> @@ -305,7 +305,7 @@
>  #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
> @@ -339,7 +339,7 @@
>  		_##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
> @@ -432,7 +432,7 @@
>   */
>  
>  /**
> - * ASSERT_EQ(expected, seen)
> + * ASSERT_EQ()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -443,7 +443,7 @@
>  	__EXPECT(expected, #expected, seen, #seen, ==, 1)
>  
>  /**
> - * ASSERT_NE(expected, seen)
> + * ASSERT_NE()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -454,7 +454,7 @@
>  	__EXPECT(expected, #expected, seen, #seen, !=, 1)
>  
>  /**
> - * ASSERT_LT(expected, seen)
> + * ASSERT_LT()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -465,7 +465,7 @@
>  	__EXPECT(expected, #expected, seen, #seen, <, 1)
>  
>  /**
> - * ASSERT_LE(expected, seen)
> + * ASSERT_LE()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -476,7 +476,7 @@
>  	__EXPECT(expected, #expected, seen, #seen, <=, 1)
>  
>  /**
> - * ASSERT_GT(expected, seen)
> + * ASSERT_GT()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -487,7 +487,7 @@
>  	__EXPECT(expected, #expected, seen, #seen, >, 1)
>  
>  /**
> - * ASSERT_GE(expected, seen)
> + * ASSERT_GE()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -498,7 +498,7 @@
>  	__EXPECT(expected, #expected, seen, #seen, >=, 1)
>  
>  /**
> - * ASSERT_NULL(seen)
> + * ASSERT_NULL()
>   *
>   * @seen: measured value
>   *
> @@ -508,7 +508,7 @@
>  	__EXPECT(NULL, "NULL", seen, #seen, ==, 1)
>  
>  /**
> - * ASSERT_TRUE(seen)
> + * ASSERT_TRUE()
>   *
>   * @seen: measured value
>   *
> @@ -518,7 +518,7 @@
>  	__EXPECT(0, "0", seen, #seen, !=, 1)
>  
>  /**
> - * ASSERT_FALSE(seen)
> + * ASSERT_FALSE()
>   *
>   * @seen: measured value
>   *
> @@ -528,7 +528,7 @@
>  	__EXPECT(0, "0", seen, #seen, ==, 1)
>  
>  /**
> - * ASSERT_STREQ(expected, seen)
> + * ASSERT_STREQ()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -539,7 +539,7 @@
>  	__EXPECT_STR(expected, seen, ==, 1)
>  
>  /**
> - * ASSERT_STRNE(expected, seen)
> + * ASSERT_STRNE()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -550,7 +550,7 @@
>  	__EXPECT_STR(expected, seen, !=, 1)
>  
>  /**
> - * EXPECT_EQ(expected, seen)
> + * EXPECT_EQ()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -561,7 +561,7 @@
>  	__EXPECT(expected, #expected, seen, #seen, ==, 0)
>  
>  /**
> - * EXPECT_NE(expected, seen)
> + * EXPECT_NE()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -572,7 +572,7 @@
>  	__EXPECT(expected, #expected, seen, #seen, !=, 0)
>  
>  /**
> - * EXPECT_LT(expected, seen)
> + * EXPECT_LT()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -583,7 +583,7 @@
>  	__EXPECT(expected, #expected, seen, #seen, <, 0)
>  
>  /**
> - * EXPECT_LE(expected, seen)
> + * EXPECT_LE()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -594,7 +594,7 @@
>  	__EXPECT(expected, #expected, seen, #seen, <=, 0)
>  
>  /**
> - * EXPECT_GT(expected, seen)
> + * EXPECT_GT()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -605,7 +605,7 @@
>  	__EXPECT(expected, #expected, seen, #seen, >, 0)
>  
>  /**
> - * EXPECT_GE(expected, seen)
> + * EXPECT_GE()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -616,7 +616,7 @@
>  	__EXPECT(expected, #expected, seen, #seen, >=, 0)
>  
>  /**
> - * EXPECT_NULL(seen)
> + * EXPECT_NULL()
>   *
>   * @seen: measured value
>   *
> @@ -626,7 +626,7 @@
>  	__EXPECT(NULL, "NULL", seen, #seen, ==, 0)
>  
>  /**
> - * EXPECT_TRUE(seen)
> + * EXPECT_TRUE()
>   *
>   * @seen: measured value
>   *
> @@ -636,7 +636,7 @@
>  	__EXPECT(0, "0", seen, #seen, !=, 0)
>  
>  /**
> - * EXPECT_FALSE(seen)
> + * EXPECT_FALSE()
>   *
>   * @seen: measured value
>   *
> @@ -646,7 +646,7 @@
>  	__EXPECT(0, "0", seen, #seen, ==, 0)
>  
>  /**
> - * EXPECT_STREQ(expected, seen)
> + * EXPECT_STREQ()
>   *
>   * @expected: expected value
>   * @seen: measured value
> @@ -657,7 +657,7 @@
>  	__EXPECT_STR(expected, seen, ==, 0)
>  
>  /**
> - * EXPECT_STRNE(expected, seen)
> + * EXPECT_STRNE()
>   *
>   * @expected: expected value
>   * @seen: measured value
> -- 
> 2.26.2
> 

-- 
Kees Cook

Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup

[Kees Cook]

On Fri, Oct 23, 2020 at 06:33:36PM +0200, Mauro Carvalho Chehab wrote:
> The documented typedef just after the kernel-doc markup
> is named "refcount_struct".
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  include/linux/refcount.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/linux/refcount.h b/include/linux/refcount.h
> index 497990c69b0b..8f431b0e69e4 100644
> --- a/include/linux/refcount.h
> +++ b/include/linux/refcount.h
> @@ -101,7 +101,7 @@
>  struct mutex;
>  
>  /**
> - * struct refcount_t - variant of atomic_t specialized for reference counts
> + * struct refcount_struct - variant of atomic_t specialized for reference counts

Hm, this is a weird one. Yes, it's actually "struct refcount_struct",
but the usage should be refcount_t (through the typedef). I'm not sure
what the right way to document this is.

-Kees

>   * @refs: atomic_t counter field
>   *
>   * The counter saturates at REFCOUNT_SATURATED and will not move once
> -- 
> 2.26.2
> 

-- 
Kees Cook

Re: [PATCH v3 37/56] pstore/zone: fix a kernel-doc markup

[Kees Cook]

On Fri, Oct 23, 2020 at 06:33:24PM +0200, Mauro Carvalho Chehab wrote:
> The documented struct is psz_head and not psz_buffer.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Reviewed-by: Kees Cook <keescook@chromium.org>

-- 
Kees Cook

Re: [PATCH v3 23/56] PCI: fix kernel-doc markups

[Bjorn Helgaas]

If you have the opportunity, I would prefer to capitalize the subject
to follow the drivers/pci convention, e.g.,

  PCI: Fix ...

On Fri, Oct 23, 2020 at 06:33:10PM +0200, Mauro Carvalho Chehab wrote:
> Some identifiers have different names between their prototypes
> and the kernel-doc markup.

How did you find these?  I build with "make W=1", which finds some
kernel-doc errors, but it didn't find these.  If there's a scanner for
these, I could fix things like this before merging them.

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

I'd be happy to take this myself, but if you want to merge the whole
series together:

Acked-by: Bjorn Helgaas <bhelgaas@google.com>

> ---
>  drivers/pci/p2pdma.c     | 10 +++++-----
>  drivers/pci/pci-driver.c |  4 ++--
>  drivers/pci/pci.c        |  2 +-
>  drivers/pci/probe.c      |  4 ++--
>  drivers/pci/slot.c       |  5 +++--
>  5 files changed, 13 insertions(+), 12 deletions(-)
> 
> diff --git a/drivers/pci/p2pdma.c b/drivers/pci/p2pdma.c
> index de1c331dbed4..bace04145c5f 100644
> --- a/drivers/pci/p2pdma.c
> +++ b/drivers/pci/p2pdma.c
> @@ -609,7 +609,7 @@ bool pci_has_p2pmem(struct pci_dev *pdev)
>  EXPORT_SYMBOL_GPL(pci_has_p2pmem);
>  
>  /**
> - * pci_p2pmem_find - find a peer-to-peer DMA memory device compatible with
> + * pci_p2pmem_find_many - find a peer-to-peer DMA memory device compatible with
>   *	the specified list of clients and shortest distance (as determined
>   *	by pci_p2pmem_dma())
>   * @clients: array of devices to check (NULL-terminated)
> @@ -674,7 +674,7 @@ struct pci_dev *pci_p2pmem_find_many(struct device **clients, int num_clients)
>  EXPORT_SYMBOL_GPL(pci_p2pmem_find_many);
>  
>  /**
> - * pci_alloc_p2p_mem - allocate peer-to-peer DMA memory
> + * pci_alloc_p2pmem - allocate peer-to-peer DMA memory
>   * @pdev: the device to allocate memory from
>   * @size: number of bytes to allocate
>   *
> @@ -727,7 +727,7 @@ void pci_free_p2pmem(struct pci_dev *pdev, void *addr, size_t size)
>  EXPORT_SYMBOL_GPL(pci_free_p2pmem);
>  
>  /**
> - * pci_virt_to_bus - return the PCI bus address for a given virtual
> + * pci_p2pmem_virt_to_bus - return the PCI bus address for a given virtual
>   *	address obtained with pci_alloc_p2pmem()
>   * @pdev: the device the memory was allocated from
>   * @addr: address of the memory that was allocated
> @@ -859,7 +859,7 @@ static int __pci_p2pdma_map_sg(struct pci_p2pdma_pagemap *p2p_pgmap,
>  }
>  
>  /**
> - * pci_p2pdma_map_sg - map a PCI peer-to-peer scatterlist for DMA
> + * pci_p2pdma_map_sg_attrs - map a PCI peer-to-peer scatterlist for DMA
>   * @dev: device doing the DMA request
>   * @sg: scatter list to map
>   * @nents: elements in the scatterlist
> @@ -896,7 +896,7 @@ int pci_p2pdma_map_sg_attrs(struct device *dev, struct scatterlist *sg,
>  EXPORT_SYMBOL_GPL(pci_p2pdma_map_sg_attrs);
>  
>  /**
> - * pci_p2pdma_unmap_sg - unmap a PCI peer-to-peer scatterlist that was
> + * pci_p2pdma_unmap_sg_attrs - unmap a PCI peer-to-peer scatterlist that was
>   *	mapped with pci_p2pdma_map_sg()
>   * @dev: device doing the DMA request
>   * @sg: scatter list to map
> diff --git a/drivers/pci/pci-driver.c b/drivers/pci/pci-driver.c
> index 8b587fc97f7b..591ab353844a 100644
> --- a/drivers/pci/pci-driver.c
> +++ b/drivers/pci/pci-driver.c
> @@ -90,7 +90,7 @@ static void pci_free_dynids(struct pci_driver *drv)
>  }
>  
>  /**
> - * store_new_id - sysfs frontend to pci_add_dynid()
> + * new_id_store - sysfs frontend to pci_add_dynid()
>   * @driver: target device driver
>   * @buf: buffer for scanning device ID data
>   * @count: input size
> @@ -158,7 +158,7 @@ static ssize_t new_id_store(struct device_driver *driver, const char *buf,
>  static DRIVER_ATTR_WO(new_id);
>  
>  /**
> - * store_remove_id - remove a PCI device ID from this driver
> + * remove_id_store - remove a PCI device ID from this driver
>   * @driver: target device driver
>   * @buf: buffer for scanning device ID data
>   * @count: input size
> diff --git a/drivers/pci/pci.c b/drivers/pci/pci.c
> index 6d4d5a2f923d..8b9bea8ba751 100644
> --- a/drivers/pci/pci.c
> +++ b/drivers/pci/pci.c
> @@ -3480,7 +3480,7 @@ bool pci_acs_enabled(struct pci_dev *pdev, u16 acs_flags)
>  }
>  
>  /**
> - * pci_acs_path_enable - test ACS flags from start to end in a hierarchy
> + * pci_acs_path_enabled - test ACS flags from start to end in a hierarchy
>   * @start: starting downstream device
>   * @end: ending upstream device or NULL to search to the root bus
>   * @acs_flags: required flags
> diff --git a/drivers/pci/probe.c b/drivers/pci/probe.c
> index 4289030b0fff..eb1ec037f9e7 100644
> --- a/drivers/pci/probe.c
> +++ b/drivers/pci/probe.c
> @@ -165,7 +165,7 @@ static inline unsigned long decode_bar(struct pci_dev *dev, u32 bar)
>  #define PCI_COMMAND_DECODE_ENABLE	(PCI_COMMAND_MEMORY | PCI_COMMAND_IO)
>  
>  /**
> - * pci_read_base - Read a PCI BAR
> + * __pci_read_base - Read a PCI BAR
>   * @dev: the PCI device
>   * @type: type of the BAR
>   * @res: resource buffer to be filled in
> @@ -1612,7 +1612,7 @@ static bool pci_ext_cfg_is_aliased(struct pci_dev *dev)
>  }
>  
>  /**
> - * pci_cfg_space_size - Get the configuration space size of the PCI device
> + * pci_cfg_space_size_ext - Get the configuration space size of the PCI device
>   * @dev: PCI device
>   *
>   * Regular PCI devices have 256 bytes, but PCI-X 2 and PCI Express devices
> diff --git a/drivers/pci/slot.c b/drivers/pci/slot.c
> index 3861505741e6..bcc8b12ce5da 100644
> --- a/drivers/pci/slot.c
> +++ b/drivers/pci/slot.c
> @@ -323,7 +323,7 @@ EXPORT_SYMBOL_GPL(pci_destroy_slot);
>  #if defined(CONFIG_HOTPLUG_PCI) || defined(CONFIG_HOTPLUG_PCI_MODULE)
>  #include <linux/pci_hotplug.h>
>  /**
> - * pci_hp_create_link - create symbolic link to the hotplug driver module.
> + * pci_hp_create_module_link - create symbolic link to the hotplug driver module.
>   * @pci_slot: struct pci_slot
>   *
>   * Helper function for pci_hotplug_core.c to create symbolic link to
> @@ -349,7 +349,8 @@ void pci_hp_create_module_link(struct pci_slot *pci_slot)
>  EXPORT_SYMBOL_GPL(pci_hp_create_module_link);
>  
>  /**
> - * pci_hp_remove_link - remove symbolic link to the hotplug driver module.
> + * pci_hp_remove_module_link - remove symbolic link to the hotplug driver
> + * 	module.
>   * @pci_slot: struct pci_slot
>   *
>   * Helper function for pci_hotplug_core.c to remove symbolic link to
> -- 
> 2.26.2
> 

Re: [PATCH v3 54/56] mm: fix kernel-doc markups

[Matthew Wilcox]

On Fri, Oct 23, 2020 at 06:33:41PM +0200, Mauro Carvalho Chehab wrote:
>  /**
> - * 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 with
> + * invalidate_mapping_pages(), except that it accounts for pages tat are

You introduced a typo here, s/tat/that/

> + * likely on a pagevec and count them in @nr_pagevec, which will used by

... and while you're touching this paragraph, s/will used/will be used/
and s/similar with/similar to/

>   * 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)
> -- 
> 2.26.2
> 
> 

Re: [PATCH v3 53/56] shed: fix kernel-doc markup

[Steven Rostedt]

On Fri, 23 Oct 2020 18:33:40 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> 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

The first change looks fine to me, but as I'm getting a new shed delivered
soon, I originally thought this email was about that delivery!

I do have a nit about the second change.

> diff --git a/kernel/sched/fair.c b/kernel/sched/fair.c
> index aa4c6227cd6d..94386fcfafcf 100644
> --- a/kernel/sched/fair.c
> +++ b/kernel/sched/fair.c
> @@ -6287,7 +6287,8 @@ static int select_idle_sibling(struct task_struct *p, int prev, int target)
>  }
>  
>  /**
> - * Amount of capacity of a CPU that is (estimated to be) used by CFS tasks
> + * cpu_util - Amount of capacity of a CPU that is (estimated to be)
> + *	used by CFS tasks

The description is to be a single line. The line break is ugly, and the 80
col rule, is more of a guideline, and not something that *has* to be done.

Either shorten it, or just let it go a little longer.

-- Steve


>   * @cpu: the CPU to get the utilization of
>   *
>   * The unit of the return value must be the one of capacity so we can compare

Re: [PATCH v3 46/56] list: fix a typo at the kernel-doc markup

[Andy Shevchenko]

On Fri, Oct 23, 2020 at 06:33:33PM +0200, Mauro Carvalho Chehab wrote:
> hlist_add_behing -> hlist_add_behind

Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

> 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 a18c87b63376..f72a7a778722 100644
> --- a/include/linux/list.h
> +++ b/include/linux/list.h
> @@ -901,7 +901,7 @@ static inline void hlist_add_before(struct hlist_node *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
>   */
> -- 
> 2.26.2
> 

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v3 01/56] scripts: kernel-doc: fix typedef parsing

[Joe Perches]

On Fri, 2020-10-23 at 11:22 -0600, Jonathan Corbet wrote:
> On Fri, 23 Oct 2020 18:32:48 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> 
> > The include/linux/genalloc.h file defined this typedef:
> > 
> > 	typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
[]
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
[]
> >      # Parse function prototypes
> > -    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > +    if ($x =~ /typedef\s+(\w+\s*){1,}\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> 
> I sure wish we could find a way to make all these regexes more
> understandable and maintainable.  Reviewing a change like this is ... fun.

Perhaps using some of the checkpatch regex definitions like:

$Type
$Ident
$balanced_parens

would help improve readability.

And the regex above doesn't quite work for spacing after typedef.
The regex should allow space between the open parenthesis and the *

	typedef <Type> ( * <Ident> ) (args...);

And this regex does not find typedefs that use another typedef as <Ident> like:

arch/s390/include/asm/debug.h:typedef int (debug_header_proc_t) (debug_info_t *id,

Re: [PATCH v3 00/56] Fix several bad kernel-doc markups

[Jakub Kicinski]

On Fri, 23 Oct 2020 18:32:47 +0200 Mauro Carvalho Chehab wrote:
> @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.

Sorry Mauro, can I hassle you for resending 18-20 as a separate series
or just loose patches to netdev?

We got a bunch of checks run on all submissions and when folks CC only
a slice of a series to netdev the CI bot thinks the series is incomplete
and doesn't pick it up :(

Re: [PATCH v3 07/56] block: blk-mq: fix a kernel-doc markup

[Jens Axboe]

On 10/23/20 10:32 AM, Mauro Carvalho Chehab wrote:
> Fix a typo:
> 	blk_mq_run_hw_queue -> blk_mq_run_hw_queues

Applied, thanks.

-- 
Jens Axboe

Re: [PATCH v3 08/56] ata: fix some kernel-doc markups

[Jens Axboe]

On 10/23/20 10:32 AM, Mauro Carvalho Chehab wrote:
> Some functions have different names between their prototypes
> and the kernel-doc markup.

Applied, thanks.


-- 
Jens Axboe

Re: [PATCH v3 00/56] Fix several bad kernel-doc markups

[Mark Brown]

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

On Fri, Oct 23, 2020 at 11:12:40AM -0700, Jakub Kicinski wrote:
> On Fri, 23 Oct 2020 18:32:47 +0200 Mauro Carvalho Chehab wrote:

> > @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.

> Sorry Mauro, can I hassle you for resending 18-20 as a separate series
> or just loose patches to netdev?

> We got a bunch of checks run on all submissions and when folks CC only
> a slice of a series to netdev the CI bot thinks the series is incomplete
> and doesn't pick it up :(

FWIW something similar with patches for different trees sent separately
would also be helpful for my automation.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH v3 48/56] sound: fix kernel-doc markups

[Mark Brown]

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

On Fri, Oct 23, 2020 at 06:33:35PM +0200, Mauro Carvalho Chehab wrote:
> Kernel-doc markups should use this format:
>         identifier - description

Acked-by: Mark Brown <broonie@kernel.org>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH v3 03/56] amdgpu: fix a few kernel-doc markup issues

[Alex Deucher]

Applied.  Thanks!

Alex

On Fri, Oct 23, 2020 at 12:38 PM Christian König
<christian.koenig@amd.com> wrote:
>
> Am 23.10.20 um 18:32 schrieb Mauro Carvalho Chehab:
> > A kernel-doc markup can't be mixed with a random comment,
> > as it causes parsing problems.
> >
> > While here, change an invalid kernel-doc markup into
> > a common comment.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> Acked-by: Christian König <christian.koenig@amd.com>
>
> > ---
> >   drivers/gpu/drm/amd/amdgpu/amdgpu_device.c | 8 +++++---
> >   1 file changed, 5 insertions(+), 3 deletions(-)
> >
> > diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
> > index f8785bdec79c..1d4b54950528 100644
> > --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
> > +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
> > @@ -239,9 +239,11 @@ bool amdgpu_device_supports_baco(struct drm_device *dev)
> >       return amdgpu_asic_supports_baco(adev);
> >   }
> >
> > +/*
> > + * VRAM access helper functions
> > + */
> > +
> >   /**
> > - * VRAM access helper functions.
> > - *
> >    * amdgpu_device_vram_access - read/write a buffer in vram
> >    *
> >    * @adev: amdgpu_device pointer
> > @@ -4497,7 +4499,7 @@ int amdgpu_device_gpu_recover(struct amdgpu_device *adev,
> >       bool need_emergency_restart = false;
> >       bool audio_suspended = false;
> >
> > -     /**
> > +     /*
> >        * Special case: RAS triggered and full reset isn't supported
> >        */
> >       need_emergency_restart = amdgpu_ras_need_emergency_restart(adev);
>
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH v3 11/56] drm/amdgpu: fix some kernel-doc markups

[Alex Deucher]

Applied.  Thanks!

Alex

On Fri, Oct 23, 2020 at 12:51 PM Christian König
<christian.koenig@amd.com> wrote:
>
> Am 23.10.20 um 18:32 schrieb Mauro Carvalho Chehab:
> > Some functions have different names between their prototypes
> > and the kernel-doc markup.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> Acked-by: Christian König <christian.koenig@amd.com>
>
> > ---
> >   drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c       | 2 +-
> >   drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 2 +-
> >   include/uapi/drm/amdgpu_drm.h                | 2 +-
> >   3 files changed, 3 insertions(+), 3 deletions(-)
> >
> > diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> > index df110afa97bf..a5f73a267fe5 100644
> > --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> > +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> > @@ -2166,7 +2166,7 @@ struct amdgpu_bo_va *amdgpu_vm_bo_add(struct amdgpu_device *adev,
> >
> >
> >   /**
> > - * amdgpu_vm_bo_insert_mapping - insert a new mapping
> > + * amdgpu_vm_bo_insert_map - insert a new mapping
> >    *
> >    * @adev: amdgpu_device pointer
> >    * @bo_va: bo_va to store the address
> > diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> > index 0c6b7c5ecfec..795bad307497 100644
> > --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> > +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> > @@ -528,7 +528,7 @@ int amdgpu_vram_mgr_alloc_sgt(struct amdgpu_device *adev,
> >   }
> >
> >   /**
> > - * amdgpu_vram_mgr_alloc_sgt - allocate and fill a sg table
> > + * amdgpu_vram_mgr_free_sgt - allocate and fill a sg table
> >    *
> >    * @adev: amdgpu device pointer
> >    * @sgt: sg table to free
> > diff --git a/include/uapi/drm/amdgpu_drm.h b/include/uapi/drm/amdgpu_drm.h
> > index c5ff2b275fcd..791a1d597d2a 100644
> > --- a/include/uapi/drm/amdgpu_drm.h
> > +++ b/include/uapi/drm/amdgpu_drm.h
> > @@ -667,7 +667,7 @@ struct drm_amdgpu_cs_chunk_data {
> >       };
> >   };
> >
> > -/**
> > +/*
> >    *  Query h/w info: Flag that this is integrated (a.h.a. fusion) GPU
> >    *
> >    */
>
> _______________________________________________
> amd-gfx mailing list
> amd-gfx@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/amd-gfx

Re: [PATCH v3 02/56] drm: amdgpu_dm: fix a typo

[Alex Deucher]

Applied.  Thanks!

Alex

On Fri, Oct 23, 2020 at 12:33 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
>         dm_comressor_info -> dm_compressor_info
>
> The kernel-doc markup is right, but the struct itself
> and their references contain a typo.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c | 2 +-
>  drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h | 6 +++---
>  2 files changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
> index bb1bc7f5d149..48ec0535d92f 100644
> --- a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
> +++ b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
> @@ -583,7 +583,7 @@ static void amdgpu_dm_fbc_init(struct drm_connector *connector)
>  {
>         struct drm_device *dev = connector->dev;
>         struct amdgpu_device *adev = drm_to_adev(dev);
> -       struct dm_comressor_info *compressor = &adev->dm.compressor;
> +       struct dm_compressor_info *compressor = &adev->dm.compressor;
>         struct amdgpu_dm_connector *aconn = to_amdgpu_dm_connector(connector);
>         struct drm_display_mode *mode;
>         unsigned long max_size = 0;
> diff --git a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
> index 34f6369bf51f..a8a0e8cb1a11 100644
> --- a/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
> +++ b/drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
> @@ -86,7 +86,7 @@ struct irq_list_head {
>   * @bo_ptr: Pointer to the buffer object
>   * @gpu_addr: MMIO gpu addr
>   */
> -struct dm_comressor_info {
> +struct dm_compressor_info {
>         void *cpu_addr;
>         struct amdgpu_bo *bo_ptr;
>         uint64_t gpu_addr;
> @@ -148,7 +148,7 @@ struct amdgpu_dm_backlight_caps {
>   * @soc_bounding_box: SOC bounding box values provided by gpu_info FW
>   * @cached_state: Caches device atomic state for suspend/resume
>   * @cached_dc_state: Cached state of content streams
> - * @compressor: Frame buffer compression buffer. See &struct dm_comressor_info
> + * @compressor: Frame buffer compression buffer. See &struct dm_compressor_info
>   * @force_timing_sync: set via debugfs. When set, indicates that all connected
>   *                    displays will be forced to synchronize.
>   */
> @@ -324,7 +324,7 @@ struct amdgpu_display_manager {
>         struct drm_atomic_state *cached_state;
>         struct dc_state *cached_dc_state;
>
> -       struct dm_comressor_info compressor;
> +       struct dm_compressor_info compressor;
>
>         const struct firmware *fw_dmcu;
>         uint32_t dmcu_fw_version;
> --
> 2.26.2
>
> _______________________________________________
> amd-gfx mailing list
> amd-gfx@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/amd-gfx

Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup

[Peter Zijlstra]

On Fri, Oct 23, 2020 at 10:40:09AM -0700, Kees Cook wrote:
> On Fri, Oct 23, 2020 at 06:33:36PM +0200, Mauro Carvalho Chehab wrote:
> > The documented typedef just after the kernel-doc markup
> > is named "refcount_struct".
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  include/linux/refcount.h | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/include/linux/refcount.h b/include/linux/refcount.h
> > index 497990c69b0b..8f431b0e69e4 100644
> > --- a/include/linux/refcount.h
> > +++ b/include/linux/refcount.h
> > @@ -101,7 +101,7 @@
> >  struct mutex;
> >  
> >  /**
> > - * struct refcount_t - variant of atomic_t specialized for reference counts
> > + * struct refcount_struct - variant of atomic_t specialized for reference counts
> 
> Hm, this is a weird one. Yes, it's actually "struct refcount_struct",
> but the usage should be refcount_t (through the typedef). I'm not sure
> what the right way to document this is.

Yeah, this is wrong. If this is due to a kernel doc warning, the kernel
doc machinery is wrong *again*.

Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup

[Jonathan Corbet]

On Fri, 23 Oct 2020 21:39:07 +0200
Peter Zijlstra <peterz@infradead.org> wrote:

> > >  /**
> > > - * struct refcount_t - variant of atomic_t specialized for reference counts
> > > + * struct refcount_struct - variant of atomic_t specialized for reference counts  
> > 
> > Hm, this is a weird one. Yes, it's actually "struct refcount_struct",
> > but the usage should be refcount_t (through the typedef). I'm not sure
> > what the right way to document this is.  
> 
> Yeah, this is wrong. If this is due to a kernel doc warning, the kernel
> doc machinery is wrong *again*.

...except that, since refcount_t is a typedef, "struct refcount_t" doesn't
actually exist.  Whether it works properly after doing s/struct// remains
to be seen...

jon

Re: [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names

[kernel test robot]

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

Hi Mauro,

I love your patch! Perhaps something to improve:

[auto build test WARNING on next-20201023]
[cannot apply to linuxtv-media/master sound/for-next pci/next mkp-scsi/for-next scsi/for-next linus/master v5.9 v5.9-rc8 v5.9-rc7 v5.9]
[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/Fix-several-bad-kernel-doc-markups/20201024-004025
base:    9695c4ff26459ff5bfe25c7d6179e4c9c00e1363
config: riscv-randconfig-r002-20201024 (attached as .config)
compiler: clang version 12.0.0 (https://github.com/llvm/llvm-project 147b9497e79a98a8614b2b5eb4ba653b44f6b6f0)
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 riscv cross compiling tool for clang build
        # apt-get install binutils-riscv64-linux-gnu
        # https://github.com/0day-ci/linux/commit/002bbfc5a97ce37daf3c570e0edd28fa0c7de5b8
        git remote add linux-review https://github.com/0day-ci/linux
        git fetch --no-tags linux-review Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20201024-004025
        git checkout 002bbfc5a97ce37daf3c570e0edd28fa0c7de5b8
        # save the attached .config to linux build tree
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=clang make.cross ARCH=riscv 

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/clk/analogbits/wrpll-cln28hpc.c:223: warning: expecting prototype for wrpll_configure(). Prototype was for wrpll_configure_for_rate() instead

vim +223 drivers/clk/analogbits/wrpll-cln28hpc.c

7b9487a9a5c41ce Paul Walmsley 2019-04-30  199  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  200  /**
7b9487a9a5c41ce Paul Walmsley 2019-04-30  201   * wrpll_configure() - compute PLL configuration for a target rate
7b9487a9a5c41ce Paul Walmsley 2019-04-30  202   * @c: ptr to a struct wrpll_cfg record to write into
7b9487a9a5c41ce Paul Walmsley 2019-04-30  203   * @target_rate: target PLL output clock rate (post-Q-divider)
7b9487a9a5c41ce Paul Walmsley 2019-04-30  204   * @parent_rate: PLL input refclk rate (pre-R-divider)
7b9487a9a5c41ce Paul Walmsley 2019-04-30  205   *
7b9487a9a5c41ce Paul Walmsley 2019-04-30  206   * Compute the appropriate PLL signal configuration values and store
7b9487a9a5c41ce Paul Walmsley 2019-04-30  207   * in PLL context @c.  PLL reprogramming is not glitchless, so the
7b9487a9a5c41ce Paul Walmsley 2019-04-30  208   * caller should switch any downstream logic to a different clock
7b9487a9a5c41ce Paul Walmsley 2019-04-30  209   * source or clock-gate it before presenting these values to the PLL
7b9487a9a5c41ce Paul Walmsley 2019-04-30  210   * configuration signals.
7b9487a9a5c41ce Paul Walmsley 2019-04-30  211   *
7b9487a9a5c41ce Paul Walmsley 2019-04-30  212   * The caller must pass this function a pre-initialized struct
7b9487a9a5c41ce Paul Walmsley 2019-04-30  213   * wrpll_cfg record: either initialized to zero (with the
7b9487a9a5c41ce Paul Walmsley 2019-04-30  214   * exception of the .name and .flags fields) or read from the PLL.
7b9487a9a5c41ce Paul Walmsley 2019-04-30  215   *
7b9487a9a5c41ce Paul Walmsley 2019-04-30  216   * Context: Any context.  Caller must protect the memory pointed to by @c
7b9487a9a5c41ce Paul Walmsley 2019-04-30  217   *          from simultaneous access or modification.
7b9487a9a5c41ce Paul Walmsley 2019-04-30  218   *
7b9487a9a5c41ce Paul Walmsley 2019-04-30  219   * Return: 0 upon success; anything else upon failure.
7b9487a9a5c41ce Paul Walmsley 2019-04-30  220   */
7b9487a9a5c41ce Paul Walmsley 2019-04-30  221  int wrpll_configure_for_rate(struct wrpll_cfg *c, u32 target_rate,
7b9487a9a5c41ce Paul Walmsley 2019-04-30  222  			     unsigned long parent_rate)
7b9487a9a5c41ce Paul Walmsley 2019-04-30 @223  {
7b9487a9a5c41ce Paul Walmsley 2019-04-30  224  	unsigned long ratio;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  225  	u64 target_vco_rate, delta, best_delta, f_pre_div, vco, vco_pre;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  226  	u32 best_f, f, post_divr_freq;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  227  	u8 fbdiv, divq, best_r, r;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  228  	int range;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  229  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  230  	if (c->flags == 0) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30  231  		WARN(1, "%s called with uninitialized PLL config", __func__);
7b9487a9a5c41ce Paul Walmsley 2019-04-30  232  		return -EINVAL;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  233  	}
7b9487a9a5c41ce Paul Walmsley 2019-04-30  234  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  235  	/* Initialize rounding data if it hasn't been initialized already */
7b9487a9a5c41ce Paul Walmsley 2019-04-30  236  	if (parent_rate != c->parent_rate) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30  237  		if (__wrpll_update_parent_rate(c, parent_rate)) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30  238  			pr_err("%s: PLL input rate is out of range\n",
7b9487a9a5c41ce Paul Walmsley 2019-04-30  239  			       __func__);
7b9487a9a5c41ce Paul Walmsley 2019-04-30  240  			return -ERANGE;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  241  		}
7b9487a9a5c41ce Paul Walmsley 2019-04-30  242  	}
7b9487a9a5c41ce Paul Walmsley 2019-04-30  243  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  244  	c->flags &= ~WRPLL_FLAGS_RESET_MASK;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  245  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  246  	/* Put the PLL into bypass if the user requests the parent clock rate */
7b9487a9a5c41ce Paul Walmsley 2019-04-30  247  	if (target_rate == parent_rate) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30  248  		c->flags |= WRPLL_FLAGS_BYPASS_MASK;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  249  		return 0;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  250  	}
7b9487a9a5c41ce Paul Walmsley 2019-04-30  251  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  252  	c->flags &= ~WRPLL_FLAGS_BYPASS_MASK;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  253  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  254  	/* Calculate the Q shift and target VCO rate */
7b9487a9a5c41ce Paul Walmsley 2019-04-30  255  	divq = __wrpll_calc_divq(target_rate, &target_vco_rate);
7b9487a9a5c41ce Paul Walmsley 2019-04-30  256  	if (!divq)
7b9487a9a5c41ce Paul Walmsley 2019-04-30  257  		return -1;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  258  	c->divq = divq;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  259  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  260  	/* Precalculate the pre-Q divider target ratio */
7b9487a9a5c41ce Paul Walmsley 2019-04-30  261  	ratio = div64_u64((target_vco_rate << ROUND_SHIFT), parent_rate);
7b9487a9a5c41ce Paul Walmsley 2019-04-30  262  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  263  	fbdiv = __wrpll_calc_fbdiv(c);
7b9487a9a5c41ce Paul Walmsley 2019-04-30  264  	best_r = 0;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  265  	best_f = 0;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  266  	best_delta = MAX_VCO_FREQ;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  267  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  268  	/*
7b9487a9a5c41ce Paul Walmsley 2019-04-30  269  	 * Consider all values for R which land within
7b9487a9a5c41ce Paul Walmsley 2019-04-30  270  	 * [MIN_POST_DIVR_FREQ, MAX_POST_DIVR_FREQ]; prefer smaller R
7b9487a9a5c41ce Paul Walmsley 2019-04-30  271  	 */
7b9487a9a5c41ce Paul Walmsley 2019-04-30  272  	for (r = c->init_r; r <= c->max_r; ++r) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30  273  		f_pre_div = ratio * r;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  274  		f = (f_pre_div + (1 << ROUND_SHIFT)) >> ROUND_SHIFT;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  275  		f >>= (fbdiv - 1);
7b9487a9a5c41ce Paul Walmsley 2019-04-30  276  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  277  		post_divr_freq = div_u64(parent_rate, r);
7b9487a9a5c41ce Paul Walmsley 2019-04-30  278  		vco_pre = fbdiv * post_divr_freq;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  279  		vco = vco_pre * f;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  280  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  281  		/* Ensure rounding didn't take us out of range */
7b9487a9a5c41ce Paul Walmsley 2019-04-30  282  		if (vco > target_vco_rate) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30  283  			--f;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  284  			vco = vco_pre * f;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  285  		} else if (vco < MIN_VCO_FREQ) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30  286  			++f;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  287  			vco = vco_pre * f;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  288  		}
7b9487a9a5c41ce Paul Walmsley 2019-04-30  289  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  290  		delta = abs(target_rate - vco);
7b9487a9a5c41ce Paul Walmsley 2019-04-30  291  		if (delta < best_delta) {
7b9487a9a5c41ce Paul Walmsley 2019-04-30  292  			best_delta = delta;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  293  			best_r = r;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  294  			best_f = f;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  295  		}
7b9487a9a5c41ce Paul Walmsley 2019-04-30  296  	}
7b9487a9a5c41ce Paul Walmsley 2019-04-30  297  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  298  	c->divr = best_r - 1;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  299  	c->divf = best_f - 1;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  300  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  301  	post_divr_freq = div_u64(parent_rate, best_r);
7b9487a9a5c41ce Paul Walmsley 2019-04-30  302  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  303  	/* Pick the best PLL jitter filter */
7b9487a9a5c41ce Paul Walmsley 2019-04-30  304  	range = __wrpll_calc_filter_range(post_divr_freq);
7b9487a9a5c41ce Paul Walmsley 2019-04-30  305  	if (range < 0)
7b9487a9a5c41ce Paul Walmsley 2019-04-30  306  		return range;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  307  	c->range = range;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  308  
7b9487a9a5c41ce Paul Walmsley 2019-04-30  309  	return 0;
7b9487a9a5c41ce Paul Walmsley 2019-04-30  310  }
7b9487a9a5c41ce Paul Walmsley 2019-04-30  311  

---
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: 25404 bytes --]

Re: [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names

[kernel test robot]

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

Hi Mauro,

I love your patch! Perhaps something to improve:

[auto build test WARNING on next-20201023]
[cannot apply to linuxtv-media/master sound/for-next pci/next mkp-scsi/for-next scsi/for-next linus/master v5.9 v5.9-rc8 v5.9-rc7 v5.9]
[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/Fix-several-bad-kernel-doc-markups/20201024-004025
base:    9695c4ff26459ff5bfe25c7d6179e4c9c00e1363
config: arm-randconfig-r005-20201024 (attached as .config)
compiler: arm-linux-gnueabi-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/002bbfc5a97ce37daf3c570e0edd28fa0c7de5b8
        git remote add linux-review https://github.com/0day-ci/linux
        git fetch --no-tags linux-review Mauro-Carvalho-Chehab/Fix-several-bad-kernel-doc-markups/20201024-004025
        git checkout 002bbfc5a97ce37daf3c570e0edd28fa0c7de5b8
        # save the attached .config to linux build tree
        COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-9.3.0 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/mm/init.c:538: warning: Function parameter or member 'perms' not described in 'update_sections_early'
   arch/arm/mm/init.c:538: warning: Function parameter or member 'n' not described in 'update_sections_early'
>> arch/arm/mm/init.c:538: warning: expecting prototype for update_sections_early intended to be called only through stop_machine(). Prototype was for update_sections_early() instead
--
>> drivers/ata/pata_legacy.c:606: warning: expecting prototype for opt82c465mv_qc_issue(). Prototype was for opti82c46x_qc_issue() instead
   drivers/ata/pata_legacy.c:933: warning: Function parameter or member 'probe' not described in 'legacy_init_one'
   drivers/ata/pata_legacy.c:933: warning: Excess function parameter 'pl' description in 'legacy_init_one'
   drivers/ata/pata_legacy.c:1024: warning: Function parameter or member 'primary' not described in 'legacy_check_special_cases'
   drivers/ata/pata_legacy.c:1024: warning: Function parameter or member 'secondary' not described in 'legacy_check_special_cases'
   drivers/ata/pata_legacy.c:1024: warning: Excess function parameter 'master' description in 'legacy_check_special_cases'
   drivers/ata/pata_legacy.c:1024: warning: Excess function parameter 'master' description in 'legacy_check_special_cases'
--
>> drivers/irqchip/irq-ixp4xx.c:259: warning: expecting prototype for ixp4x_irq_setup(). Prototype was for ixp4xx_irq_setup() instead
--
   drivers/scsi/pmcraid.c:455: warning: Function parameter or member 'intrs' not described in 'pmcraid_enable_interrupts'
   drivers/scsi/pmcraid.c:455: warning: Excess function parameter 'intr' description in 'pmcraid_enable_interrupts'
   drivers/scsi/pmcraid.c:543: warning: Function parameter or member '' not described in 'pmcraid_ioa_reset'
>> drivers/scsi/pmcraid.c:543: warning: expecting prototype for pmcraid_bist_done(). Prototype was for pmcraid_ioa_reset() instead
   drivers/scsi/pmcraid.c:603: warning: Function parameter or member 't' not described in 'pmcraid_reset_alert_done'
   drivers/scsi/pmcraid.c:603: warning: Excess function parameter 'cmd' description in 'pmcraid_reset_alert_done'
   drivers/scsi/pmcraid.c:638: warning: Function parameter or member '' not described in 'pmcraid_notify_ioastate'
   drivers/scsi/pmcraid.c:638: warning: Function parameter or member 'u32' not described in 'pmcraid_notify_ioastate'
>> drivers/scsi/pmcraid.c:638: warning: expecting prototype for pmcraid_reset_alert(). Prototype was for pmcraid_notify_ioastate() instead
   drivers/scsi/pmcraid.c:687: warning: Function parameter or member 't' not described in 'pmcraid_timeout_handler'
   drivers/scsi/pmcraid.c:687: warning: Excess function parameter 'cmd' description in 'pmcraid_timeout_handler'
>> drivers/scsi/pmcraid.c:858: warning: expecting prototype for pmcraid_fire_command(). Prototype was for _pmcraid_fire_command() instead
   drivers/scsi/pmcraid.c:972: warning: Function parameter or member '' not described in 'pmcraid_querycfg'
>> drivers/scsi/pmcraid.c:972: warning: expecting prototype for pmcraid_get_fwversion_done(). Prototype was for pmcraid_querycfg() instead
   drivers/scsi/pmcraid.c:1398: warning: Function parameter or member 'aen_msg' not described in 'pmcraid_notify_aen'
   drivers/scsi/pmcraid.c:1398: warning: Function parameter or member 'data_size' not described in 'pmcraid_notify_aen'
   drivers/scsi/pmcraid.c:1398: warning: Excess function parameter 'type' description in 'pmcraid_notify_aen'
   drivers/scsi/pmcraid.c:1781: warning: Function parameter or member '' not described in 'pmcraid_initiate_reset'
>> drivers/scsi/pmcraid.c:1781: warning: expecting prototype for pmcraid_process_ldn(). Prototype was for pmcraid_initiate_reset() instead
   drivers/scsi/pmcraid.c:1887: warning: Function parameter or member '' not described in 'pmcraid_reinit_buffers'
>> drivers/scsi/pmcraid.c:1887: warning: expecting prototype for pmcraid_reset_enable_ioa(). Prototype was for pmcraid_reinit_buffers() instead
   drivers/scsi/pmcraid.c:2704: warning: Function parameter or member 'timeout' not described in 'pmcraid_reset_device'
>> drivers/scsi/pmcraid.c:3025: warning: expecting prototype for pmcraid_eh_xxxx_reset_handler(). Prototype was for pmcraid_eh_device_reset_handler() instead
>> drivers/scsi/pmcraid.c:3327: warning: expecting prototype for pmcraid_queuecommand(). Prototype was for pmcraid_queuecommand_lck() instead
   drivers/scsi/pmcraid.c:3437: warning: Function parameter or member 'inode' not described in 'pmcraid_chr_open'
   drivers/scsi/pmcraid.c:3437: warning: Function parameter or member 'filep' not described in 'pmcraid_chr_open'
>> drivers/scsi/pmcraid.c:3437: warning: expecting prototype for pmcraid_open(). Prototype was for pmcraid_chr_open() instead
   drivers/scsi/pmcraid.c:3457: warning: Function parameter or member 'fd' not described in 'pmcraid_chr_fasync'
   drivers/scsi/pmcraid.c:3457: warning: Function parameter or member 'filep' not described in 'pmcraid_chr_fasync'
   drivers/scsi/pmcraid.c:3457: warning: Function parameter or member 'mode' not described in 'pmcraid_chr_fasync'
>> drivers/scsi/pmcraid.c:3457: warning: expecting prototype for pmcraid_fasync(). Prototype was for pmcraid_chr_fasync() instead
   drivers/scsi/pmcraid.c:3574: warning: Function parameter or member 'ioctl_cmd' not described in 'pmcraid_ioctl_passthrough'
   drivers/scsi/pmcraid.c:3574: warning: Function parameter or member 'buflen' not described in 'pmcraid_ioctl_passthrough'
   drivers/scsi/pmcraid.c:3574: warning: Excess function parameter 'cmd' description in 'pmcraid_ioctl_passthrough'
   drivers/scsi/pmcraid.c:3905: warning: Function parameter or member 'filep' not described in 'pmcraid_chr_ioctl'
   drivers/scsi/pmcraid.c:3905: warning: Function parameter or member 'cmd' not described in 'pmcraid_chr_ioctl'
   drivers/scsi/pmcraid.c:3905: warning: Function parameter or member 'arg' not described in 'pmcraid_chr_ioctl'
>> drivers/scsi/pmcraid.c:3905: warning: expecting prototype for pmcraid_ioctl(). Prototype was for pmcraid_chr_ioctl() instead
   drivers/scsi/pmcraid.c:3969: warning: cannot understand function prototype: 'const struct file_operations pmcraid_fops = '
   drivers/scsi/pmcraid.c:3993: warning: Function parameter or member 'attr' not described in 'pmcraid_show_log_level'
   drivers/scsi/pmcraid.c:4015: warning: Function parameter or member 'attr' not described in 'pmcraid_store_log_level'
   drivers/scsi/pmcraid.c:4055: warning: Function parameter or member 'attr' not described in 'pmcraid_show_drv_version'
   drivers/scsi/pmcraid.c:4081: warning: Function parameter or member 'attr' not described in 'pmcraid_show_adapter_id'
>> drivers/scsi/pmcraid.c:4081: warning: expecting prototype for pmcraid_show_io_adapter_id(). Prototype was for pmcraid_show_adapter_id() instead
   drivers/scsi/pmcraid.c:4600: warning: Function parameter or member 'pinstance' not described in 'pmcraid_allocate_cmd_blocks'
   drivers/scsi/pmcraid.c:5153: warning: Function parameter or member 'minor' not described in 'pmcraid_release_minor'
--
   drivers/vfio/vfio.c:224: warning: Function parameter or member 'ops' not described in 'vfio_register_iommu_driver'
>> drivers/vfio/vfio.c:224: warning: expecting prototype for IOMMU driver registration(). Prototype was for vfio_register_iommu_driver() instead
   drivers/vfio/vfio.c:273: warning: Function parameter or member 'group' not described in 'vfio_alloc_group_minor'
>> drivers/vfio/vfio.c:273: warning: expecting prototype for free(). Prototype was for vfio_alloc_group_minor() instead
   drivers/vfio/vfio.c:293: warning: Function parameter or member 'container' not described in 'vfio_container_get'
>> drivers/vfio/vfio.c:293: warning: expecting prototype for Container objects(). Prototype was for vfio_container_get() instead
   drivers/vfio/vfio.c:325: warning: Function parameter or member 'iommu_group' not described in 'vfio_create_group'
>> drivers/vfio/vfio.c:325: warning: expecting prototype for Group objects(). Prototype was for vfio_create_group() instead
   drivers/vfio/vfio.c:540: warning: Function parameter or member 'group' not described in 'vfio_group_create_device'
   drivers/vfio/vfio.c:540: warning: Function parameter or member 'dev' not described in 'vfio_group_create_device'
   drivers/vfio/vfio.c:540: warning: Function parameter or member 'ops' not described in 'vfio_group_create_device'
   drivers/vfio/vfio.c:540: warning: Function parameter or member 'device_data' not described in 'vfio_group_create_device'
>> drivers/vfio/vfio.c:540: warning: expecting prototype for Device objects(). Prototype was for vfio_group_create_device() instead
   drivers/vfio/vfio.c:694: warning: Function parameter or member 'group' not described in 'vfio_group_nb_add_dev'
   drivers/vfio/vfio.c:694: warning: Function parameter or member 'dev' not described in 'vfio_group_nb_add_dev'
>> drivers/vfio/vfio.c:694: warning: expecting prototype for Async device support(). Prototype was for vfio_group_nb_add_dev() instead
   drivers/vfio/vfio.c:806: warning: Function parameter or member 'dev' not described in 'vfio_add_group_dev'
   drivers/vfio/vfio.c:806: warning: Function parameter or member 'ops' not described in 'vfio_add_group_dev'
   drivers/vfio/vfio.c:806: warning: Function parameter or member 'device_data' not described in 'vfio_add_group_dev'
>> drivers/vfio/vfio.c:806: warning: expecting prototype for VFIO driver API(). Prototype was for vfio_add_group_dev() instead
   drivers/vfio/vfio.c:864: warning: Function parameter or member 'dev' not described in 'vfio_device_get_from_dev'
>> drivers/vfio/vfio.c:864: warning: expecting prototype for Even if the(). Prototype was for vfio_device_get_from_dev() instead
   drivers/vfio/vfio.c:1022: warning: Function parameter or member 'container' not described in 'vfio_ioctl_check_extension'
   drivers/vfio/vfio.c:1022: warning: Function parameter or member 'arg' not described in 'vfio_ioctl_check_extension'
>> drivers/vfio/vfio.c:1022: warning: expecting prototype for vfio(). Prototype was for vfio_ioctl_check_extension() instead
   drivers/vfio/vfio.c:1293: warning: Function parameter or member 'group' not described in '__vfio_group_unset_container'
>> drivers/vfio/vfio.c:1293: warning: expecting prototype for GROUP(). Prototype was for __vfio_group_unset_container() instead
   drivers/vfio/vfio.c:1628: warning: Function parameter or member 'inode' not described in 'vfio_device_fops_release'
   drivers/vfio/vfio.c:1628: warning: Function parameter or member 'filep' not described in 'vfio_device_fops_release'
>> drivers/vfio/vfio.c:1628: warning: expecting prototype for VFIO Device fd(). Prototype was for vfio_device_fops_release() instead
>> drivers/vfio/vfio.c:1695: warning: wrong kernel-doc identifier on line:
    * External user API, exported by symbols to be linked dynamically.
   drivers/vfio/vfio.c:1740: warning: wrong kernel-doc identifier on line:
    * External user API, exported by symbols to be linked dynamically.
   drivers/vfio/vfio.c:1819: warning: Function parameter or member 'caps' not described in 'vfio_info_cap_add'
   drivers/vfio/vfio.c:1819: warning: Function parameter or member 'size' not described in 'vfio_info_cap_add'
   drivers/vfio/vfio.c:1819: warning: Function parameter or member 'id' not described in 'vfio_info_cap_add'
   drivers/vfio/vfio.c:1819: warning: Function parameter or member 'version' not described in 'vfio_info_cap_add'
>> drivers/vfio/vfio.c:1819: warning: expecting prototype for Sub(). Prototype was for vfio_info_cap_add() instead
   drivers/vfio/vfio.c:2338: warning: Function parameter or member 'dev' not described in 'vfio_devnode'
   drivers/vfio/vfio.c:2338: warning: Function parameter or member 'mode' not described in 'vfio_devnode'
>> drivers/vfio/vfio.c:2338: warning: expecting prototype for class support(). Prototype was for vfio_devnode() instead
--
>> drivers/mmc/core/queue.c:212: warning: expecting prototype for mmc_init_request(). Prototype was for __mmc_init_request() instead
--
>> drivers/crypto/chelsio/chcr_core.c:2: warning: wrong kernel-doc identifier on line:
    * This file is part of the Chelsio T4/T5/T6 Ethernet driver for Linux.
--
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1854: warning: Function parameter or member 'host' not described in 'brcmnand_edu_trans'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1854: warning: Function parameter or member 'addr' not described in 'brcmnand_edu_trans'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1854: warning: Function parameter or member 'buf' not described in 'brcmnand_edu_trans'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1854: warning: Function parameter or member 'len' not described in 'brcmnand_edu_trans'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1854: warning: Function parameter or member 'cmd' not described in 'brcmnand_edu_trans'
>> drivers/mtd/nand/raw/brcmnand/brcmnand.c:1854: warning: expecting prototype for Kick EDU engine(). Prototype was for brcmnand_edu_trans() instead
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'host' not described in 'brcmnand_fill_dma_desc'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'desc' not described in 'brcmnand_fill_dma_desc'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'addr' not described in 'brcmnand_fill_dma_desc'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'buf' not described in 'brcmnand_fill_dma_desc'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'len' not described in 'brcmnand_fill_dma_desc'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'dma_cmd' not described in 'brcmnand_fill_dma_desc'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'begin' not described in 'brcmnand_fill_dma_desc'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'end' not described in 'brcmnand_fill_dma_desc'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: Function parameter or member 'next_desc' not described in 'brcmnand_fill_dma_desc'
>> drivers/mtd/nand/raw/brcmnand/brcmnand.c:1951: warning: expecting prototype for You must know the(). Prototype was for brcmnand_fill_dma_desc() instead
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1977: warning: Function parameter or member 'host' not described in 'brcmnand_dma_run'
   drivers/mtd/nand/raw/brcmnand/brcmnand.c:1977: warning: Function parameter or member 'desc' not described in 'brcmnand_dma_run'
>> drivers/mtd/nand/raw/brcmnand/brcmnand.c:1977: warning: expecting prototype for with a given DMA descriptor(). Prototype was for brcmnand_dma_run() instead
--
>> drivers/net/wireless/intel/ipw2x00/ipw2100.c:5375: warning: expecting prototype for Set a the wep key(). Prototype was for ipw2100_set_key() instead
>> drivers/net/wireless/intel/ipw2x00/ipw2100.c:6542: warning: expecting prototype for module(). Prototype was for ipw2100_init() instead
>> drivers/net/wireless/intel/ipw2x00/ipw2100.c:6568: warning: expecting prototype for Cleanup ipw2100 driver registration(). Prototype was for ipw2100_exit() instead
--
>> drivers/net/ethernet/chelsio/cxgb4/cxgb4_ptp.c:455: warning: expecting prototype for cxgb4_ptp_remove(). Prototype was for cxgb4_ptp_stop() instead
--
>> drivers/net/ethernet/chelsio/cxgb4/t4_hw.c:7000: warning: expecting prototype for t4_init_cmd(). Prototype was for t4_early_init() instead
>> drivers/net/ethernet/chelsio/cxgb4/t4_hw.c:10241: warning: expecting prototype for t4_set_vf_mac(). Prototype was for t4_set_vf_mac_acl() instead
..

vim +538 arch/arm/mm/init.c

1e6b48116a9504 Kees Cook         2014-04-03  531  
11ce4b33aedc65 Grygorii Strashko 2017-04-25  532  /**
11ce4b33aedc65 Grygorii Strashko 2017-04-25  533   * update_sections_early intended to be called only through stop_machine
11ce4b33aedc65 Grygorii Strashko 2017-04-25  534   * framework and executed by only one CPU while all other CPUs will spin and
11ce4b33aedc65 Grygorii Strashko 2017-04-25  535   * wait, so no locking is required in this function.
11ce4b33aedc65 Grygorii Strashko 2017-04-25  536   */
08925c2f124f1b Laura Abbott      2015-11-30  537  static void update_sections_early(struct section_perm perms[], int n)
1e6b48116a9504 Kees Cook         2014-04-03 @538  {
08925c2f124f1b Laura Abbott      2015-11-30  539  	struct task_struct *t, *s;
08925c2f124f1b Laura Abbott      2015-11-30  540  
08925c2f124f1b Laura Abbott      2015-11-30  541  	for_each_process(t) {
08925c2f124f1b Laura Abbott      2015-11-30  542  		if (t->flags & PF_KTHREAD)
08925c2f124f1b Laura Abbott      2015-11-30  543  			continue;
08925c2f124f1b Laura Abbott      2015-11-30  544  		for_each_thread(t, s)
c51bc12d06b3a5 Doug Berger       2019-07-01  545  			if (s->mm)
08925c2f124f1b Laura Abbott      2015-11-30  546  				set_section_perms(perms, n, true, s->mm);
08925c2f124f1b Laura Abbott      2015-11-30  547  	}
08925c2f124f1b Laura Abbott      2015-11-30  548  	set_section_perms(perms, n, true, current->active_mm);
08925c2f124f1b Laura Abbott      2015-11-30  549  	set_section_perms(perms, n, true, &init_mm);
08925c2f124f1b Laura Abbott      2015-11-30  550  }
08925c2f124f1b Laura Abbott      2015-11-30  551  

---
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: 33248 bytes --]

Re: [PATCH v3 46/56] list: fix a typo at the kernel-doc markup

[Paul E. McKenney]

On Fri, Oct 23, 2020 at 06:33:33PM +0200, Mauro Carvalho Chehab wrote:
> hlist_add_behing -> hlist_add_behind
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Acked-by: Paul E. McKenney <paulmck@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 a18c87b63376..f72a7a778722 100644
> --- a/include/linux/list.h
> +++ b/include/linux/list.h
> @@ -901,7 +901,7 @@ static inline void hlist_add_before(struct hlist_node *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
>   */
> -- 
> 2.26.2
> 

Re: [PATCH v3 18/56] net: phy: fix kernel-doc markups

[Andrew Lunn]

On Fri, Oct 23, 2020 at 06:33:05PM +0200, Mauro Carvalho Chehab wrote:
> Some functions have different names between their prototypes
> and the kernel-doc markup.
> 
> 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
> @@ -472,7 +472,7 @@ static inline void of_mdiobus_link_mdiodev(struct mii_bus *mdio,
>  #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

Hi Mauro

If you need to repost, could you make use of:

-U<n>
--unified=<n>
Generate diffs with <n> lines of context instead of the usual three.

to increase the number of lines of context. Often three lines is not
enough to include the function declaration in the patch, so i need to
go look at the sources to do a review. 

Reviewed-by: Andrew Lunn <andrew@lunn.ch>

    Andrew

Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup

[Mauro Carvalho Chehab]

Em Fri, 23 Oct 2020 13:47:57 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Fri, 23 Oct 2020 21:39:07 +0200
> Peter Zijlstra <peterz@infradead.org> wrote:
> 
> > > >  /**
> > > > - * struct refcount_t - variant of atomic_t specialized for reference counts
> > > > + * struct refcount_struct - variant of atomic_t specialized for reference counts    
> > > 
> > > Hm, this is a weird one. Yes, it's actually "struct refcount_struct",
> > > but the usage should be refcount_t (through the typedef). I'm not sure
> > > what the right way to document this is.    
> > 
> > Yeah, this is wrong. If this is due to a kernel doc warning, the kernel
> > doc machinery is wrong *again*.  

This issue has nothing to do with warnings. The problem here is that
"struct" is a markup for structs, and not for typedefs.

> 
> ...except that, since refcount_t is a typedef, "struct refcount_t" doesn't
> actually exist.  Whether it works properly after doing s/struct// remains
> to be seen...

If the intent is to document the struct and its internal fields,
this kernel-doc should work:

	/**
	 * struct refcount_struct - variant of atomic_t specialized for reference counts
	 * @refs: atomic_t counter field
	 *
	 * The counter saturates at REFCOUNT_SATURATED and will not move once
	 * there. This avoids wrapping the counter and causing 'spurious'
	 * use-after-free bugs.
	 */

Which produces this result:

	.. c:struct:: refcount_struct

	   variant of atomic_t specialized for reference counts

	**Definition**

	::

	  struct refcount_struct {
	    atomic_t refs;
	  };

	**Members**

	``refs``
	  atomic_t counter field

	(description)

See, in this case, the identifier is not opaque: its members are
documented at the html (or man) output.

If you want, instead, to document the typedef, this is the
proper way:

	/**
	 * typedef refcount_t - variant of atomic_t specialized for reference counts
	 *
	 * The counter saturates at REFCOUNT_SATURATED and will not move once
	 * there. This avoids wrapping the counter and causing 'spurious'
	 * use-after-free bugs.
	 */

It will handle this one as an opaque type, meaning that it won't be 
showing the "refs" field - even if you forget to drop the @refs: 
at the markup. The result will be:


	.. c:type:: refcount_t

	   variant of atomic_t specialized for reference counts

	(description)

-

If you want both, then you would either split struct and typedef, e. g.
with something like:

	/**
	 * struct refcount_struct - variant of atomic_t specialized for reference counts
	 * @refs: atomic_t counter field
	 *
	 * The counter saturates at REFCOUNT_SATURATED and will not move once
	 * there. This avoids wrapping the counter and causing 'spurious'
	 * use-after-free bugs.
	 */
	struct refcount_struct {
	        atomic_t refs;
	};

	/**
	 * typedef refcount_t - variant of atomic_t specialized for reference counts
	 * @refs: atomic_t counter field
	 *
	 * The counter saturates at REFCOUNT_SATURATED and will not move once
	 * there. This avoids wrapping the counter and causing 'spurious'
	 * use-after-free bugs.
	 */
	typedef struct refcount_struct refcount_t;

Or, you could add the member at the description field. E. g. something
like this:

	/**
	 * typedef refcount_t - variant of atomic_t specialized for reference counts
	 *
	 * The counter saturates at REFCOUNT_SATURATED and will not move once
	 * there. This avoids wrapping the counter and causing 'spurious'
	 * use-after-free bugs.
	 *
	 * Members:
	 *   ``refs``
	 *        atomic_t counter field
	 */
	typedef struct refcount_struct {
	        atomic_t refs;
	} refcount_t;

If you want to test it, you can run kernel-doc directly, to see how
it will parse it. For ReST output, that's the syntax:

	./scripts/kernel-doc --sphinx-version 3 include/linux/refcount.h

Thanks,
Mauro

Re: [PATCH v3 01/56] scripts: kernel-doc: fix typedef parsing

[Mauro Carvalho Chehab]

Em Fri, 23 Oct 2020 11:22:26 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Fri, 23 Oct 2020 18:32:48 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> 
> > The include/linux/genalloc.h file defined this typedef:
> > 
> > 	typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
> > 
> > Because it has a type composite of two words (unsigned long),
> > the parser gets the typedef name wrong:
> > 
> > .. c:macro:: long
> > 
> >    **Typedef**: Allocation callback function type definition
> > 
> > Fix the regex in order to accept composite types when
> > defining a typedef for a function pointer.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  scripts/kernel-doc | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index 99cd8418ff8a..311d213ee74d 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -1438,7 +1438,7 @@ sub dump_typedef($$) {
> >      $x =~ s@/\*.*?\*/@@gos;	# strip comments.
> >  
> >      # Parse function prototypes
> > -    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > +    if ($x =~ /typedef\s+(\w+\s*){1,}\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||  
> 
> I sure wish we could find a way to make all these regexes more
> understandable and maintainable.  Reviewing a change like this is ... fun.

Yeah. Regexes can be take a while to check. Btw, there's a site that
is really cool to check things:

	https://regex101.com/

Unfortunately, it doesn't support Perl flavor. So, you may still
need to double-check if Perl will handle the regex the same way[1].

[1] One of the differences I found is with regards to match repetitions
    https://perldoc.perl.org/perlrequick#Matching-repetitions
    This works on both Python and Perl:
	(foo){0,2}
    But this only works on Python:
	(foo){,2}

> 
> Anyway, it seems to work, but it does now include trailing whitespace in
> the type portion.  So, for example, from include/linux/xarray.h:
> 
>   typedef void (*xa_update_node_t)(struct xa_node *node);
> 
> The type is parsed as "void " where it was "void" before.  The only ill
> effect I can see is that some non-breaking spaces get inserted into the
> HTML output, but perhaps it's worth stripping off that trailing space
> anyway?

Ok, I'll work on a second version addressing it.

Thanks,
Mauro

Re: [PATCH v3 23/56] PCI: fix kernel-doc markups

[Mauro Carvalho Chehab]

Em Fri, 23 Oct 2020 12:43:25 -0500
Bjorn Helgaas <helgaas@kernel.org> escreveu:

> If you have the opportunity, I would prefer to capitalize the subject
> to follow the drivers/pci convention, e.g.,
> 
>   PCI: Fix ...

Ok. If you want to apply it directly, feel free to change it
at the patch.

Otherwise, I'll do it on a next rebase.

> 
> On Fri, Oct 23, 2020 at 06:33:10PM +0200, Mauro Carvalho Chehab wrote:
> > Some identifiers have different names between their prototypes
> > and the kernel-doc markup.  
> 
> How did you find these?  I build with "make W=1", which finds some
> kernel-doc errors, but it didn't find these.  If there's a scanner for
> these, I could fix things like this before merging them.

This is a new check. See patch 56/56.

Right now, kernel-doc will just silently ignore the identifier
from kernel-doc markup and use the one defined at the function
or data struct prototype.

Once all the issues gets fixed, patch 56/56 can be merged.

> 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> 
> I'd be happy to take this myself, but if you want to merge the whole
> series together:
> 
> Acked-by: Bjorn Helgaas <bhelgaas@google.com>

Either way works for me, although IMO it should be simpler if
you could pick it directly, as it will avoid potential
merge conflicts if such patches go via their usual trees.

> 
> > ---
> >  drivers/pci/p2pdma.c     | 10 +++++-----
> >  drivers/pci/pci-driver.c |  4 ++--
> >  drivers/pci/pci.c        |  2 +-
> >  drivers/pci/probe.c      |  4 ++--
> >  drivers/pci/slot.c       |  5 +++--
> >  5 files changed, 13 insertions(+), 12 deletions(-)
> > 
> > diff --git a/drivers/pci/p2pdma.c b/drivers/pci/p2pdma.c
> > index de1c331dbed4..bace04145c5f 100644
> > --- a/drivers/pci/p2pdma.c
> > +++ b/drivers/pci/p2pdma.c
> > @@ -609,7 +609,7 @@ bool pci_has_p2pmem(struct pci_dev *pdev)
> >  EXPORT_SYMBOL_GPL(pci_has_p2pmem);
> >  
> >  /**
> > - * pci_p2pmem_find - find a peer-to-peer DMA memory device compatible with
> > + * pci_p2pmem_find_many - find a peer-to-peer DMA memory device compatible with
> >   *	the specified list of clients and shortest distance (as determined
> >   *	by pci_p2pmem_dma())
> >   * @clients: array of devices to check (NULL-terminated)
> > @@ -674,7 +674,7 @@ struct pci_dev *pci_p2pmem_find_many(struct device **clients, int num_clients)
> >  EXPORT_SYMBOL_GPL(pci_p2pmem_find_many);
> >  
> >  /**
> > - * pci_alloc_p2p_mem - allocate peer-to-peer DMA memory
> > + * pci_alloc_p2pmem - allocate peer-to-peer DMA memory
> >   * @pdev: the device to allocate memory from
> >   * @size: number of bytes to allocate
> >   *
> > @@ -727,7 +727,7 @@ void pci_free_p2pmem(struct pci_dev *pdev, void *addr, size_t size)
> >  EXPORT_SYMBOL_GPL(pci_free_p2pmem);
> >  
> >  /**
> > - * pci_virt_to_bus - return the PCI bus address for a given virtual
> > + * pci_p2pmem_virt_to_bus - return the PCI bus address for a given virtual
> >   *	address obtained with pci_alloc_p2pmem()
> >   * @pdev: the device the memory was allocated from
> >   * @addr: address of the memory that was allocated
> > @@ -859,7 +859,7 @@ static int __pci_p2pdma_map_sg(struct pci_p2pdma_pagemap *p2p_pgmap,
> >  }
> >  
> >  /**
> > - * pci_p2pdma_map_sg - map a PCI peer-to-peer scatterlist for DMA
> > + * pci_p2pdma_map_sg_attrs - map a PCI peer-to-peer scatterlist for DMA
> >   * @dev: device doing the DMA request
> >   * @sg: scatter list to map
> >   * @nents: elements in the scatterlist
> > @@ -896,7 +896,7 @@ int pci_p2pdma_map_sg_attrs(struct device *dev, struct scatterlist *sg,
> >  EXPORT_SYMBOL_GPL(pci_p2pdma_map_sg_attrs);
> >  
> >  /**
> > - * pci_p2pdma_unmap_sg - unmap a PCI peer-to-peer scatterlist that was
> > + * pci_p2pdma_unmap_sg_attrs - unmap a PCI peer-to-peer scatterlist that was
> >   *	mapped with pci_p2pdma_map_sg()
> >   * @dev: device doing the DMA request
> >   * @sg: scatter list to map
> > diff --git a/drivers/pci/pci-driver.c b/drivers/pci/pci-driver.c
> > index 8b587fc97f7b..591ab353844a 100644
> > --- a/drivers/pci/pci-driver.c
> > +++ b/drivers/pci/pci-driver.c
> > @@ -90,7 +90,7 @@ static void pci_free_dynids(struct pci_driver *drv)
> >  }
> >  
> >  /**
> > - * store_new_id - sysfs frontend to pci_add_dynid()
> > + * new_id_store - sysfs frontend to pci_add_dynid()
> >   * @driver: target device driver
> >   * @buf: buffer for scanning device ID data
> >   * @count: input size
> > @@ -158,7 +158,7 @@ static ssize_t new_id_store(struct device_driver *driver, const char *buf,
> >  static DRIVER_ATTR_WO(new_id);
> >  
> >  /**
> > - * store_remove_id - remove a PCI device ID from this driver
> > + * remove_id_store - remove a PCI device ID from this driver
> >   * @driver: target device driver
> >   * @buf: buffer for scanning device ID data
> >   * @count: input size
> > diff --git a/drivers/pci/pci.c b/drivers/pci/pci.c
> > index 6d4d5a2f923d..8b9bea8ba751 100644
> > --- a/drivers/pci/pci.c
> > +++ b/drivers/pci/pci.c
> > @@ -3480,7 +3480,7 @@ bool pci_acs_enabled(struct pci_dev *pdev, u16 acs_flags)
> >  }
> >  
> >  /**
> > - * pci_acs_path_enable - test ACS flags from start to end in a hierarchy
> > + * pci_acs_path_enabled - test ACS flags from start to end in a hierarchy
> >   * @start: starting downstream device
> >   * @end: ending upstream device or NULL to search to the root bus
> >   * @acs_flags: required flags
> > diff --git a/drivers/pci/probe.c b/drivers/pci/probe.c
> > index 4289030b0fff..eb1ec037f9e7 100644
> > --- a/drivers/pci/probe.c
> > +++ b/drivers/pci/probe.c
> > @@ -165,7 +165,7 @@ static inline unsigned long decode_bar(struct pci_dev *dev, u32 bar)
> >  #define PCI_COMMAND_DECODE_ENABLE	(PCI_COMMAND_MEMORY | PCI_COMMAND_IO)
> >  
> >  /**
> > - * pci_read_base - Read a PCI BAR
> > + * __pci_read_base - Read a PCI BAR
> >   * @dev: the PCI device
> >   * @type: type of the BAR
> >   * @res: resource buffer to be filled in
> > @@ -1612,7 +1612,7 @@ static bool pci_ext_cfg_is_aliased(struct pci_dev *dev)
> >  }
> >  
> >  /**
> > - * pci_cfg_space_size - Get the configuration space size of the PCI device
> > + * pci_cfg_space_size_ext - Get the configuration space size of the PCI device
> >   * @dev: PCI device
> >   *
> >   * Regular PCI devices have 256 bytes, but PCI-X 2 and PCI Express devices
> > diff --git a/drivers/pci/slot.c b/drivers/pci/slot.c
> > index 3861505741e6..bcc8b12ce5da 100644
> > --- a/drivers/pci/slot.c
> > +++ b/drivers/pci/slot.c
> > @@ -323,7 +323,7 @@ EXPORT_SYMBOL_GPL(pci_destroy_slot);
> >  #if defined(CONFIG_HOTPLUG_PCI) || defined(CONFIG_HOTPLUG_PCI_MODULE)
> >  #include <linux/pci_hotplug.h>
> >  /**
> > - * pci_hp_create_link - create symbolic link to the hotplug driver module.
> > + * pci_hp_create_module_link - create symbolic link to the hotplug driver module.
> >   * @pci_slot: struct pci_slot
> >   *
> >   * Helper function for pci_hotplug_core.c to create symbolic link to
> > @@ -349,7 +349,8 @@ void pci_hp_create_module_link(struct pci_slot *pci_slot)
> >  EXPORT_SYMBOL_GPL(pci_hp_create_module_link);
> >  
> >  /**
> > - * pci_hp_remove_link - remove symbolic link to the hotplug driver module.
> > + * pci_hp_remove_module_link - remove symbolic link to the hotplug driver
> > + * 	module.
> >   * @pci_slot: struct pci_slot
> >   *
> >   * Helper function for pci_hotplug_core.c to remove symbolic link to
> > -- 
> > 2.26.2
> >   



Thanks,
Mauro

Re: [PATCH v3 14/56] IB: fix kernel-doc markups

[Max Gurtovoy]

Thanks Mauro, small fix for iser

On 10/23/2020 7:33 PM, Mauro Carvalho Chehab wrote:
> 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>
>
> diff --git a/drivers/infiniband/ulp/iser/iscsi_iser.c b/drivers/infiniband/ulp/iser/iscsi_iser.c
> index 3690e28cc7ea..84cebf937680 100644
> --- a/drivers/infiniband/ulp/iser/iscsi_iser.c
> +++ b/drivers/infiniband/ulp/iser/iscsi_iser.c
> @@ -739,7 +739,7 @@ iscsi_iser_set_param(struct iscsi_cls_conn *cls_conn,
>   }
>   
>   /**
> - * iscsi_iser_set_param() - set class connection parameter
> + * iscsi_iser_conn_get_stats() - set class connection parameter

iscsi_iser_conn_get_stats() - get iscsi connection statistics


>    * @cls_conn:    iscsi class connection
>    * @stats:       iscsi stats to output
>    *
>   

Re: [PATCH v3 47/56] memblock: fix kernel-doc markups

[Mike Rapoport]

On Fri, Oct 23, 2020 at 06:33:34PM +0200, 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: Mike Rapoport <rppt@linux.ibm.com>

> ---
>  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
> @@ -272,7 +272,7 @@ 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
> @@ -292,7 +292,7 @@ void __next_mem_pfn_range_in_zone(u64 *idx, struct zone *zone,
>  	     __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
> -- 
> 2.26.2
> 

-- 
Sincerely yours,
Mike.

Re: [PATCH v3 51/56] audit: fix a kernel-doc markup

[Paul Moore]

On Fri, Oct 23, 2020 at 12:33 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> typo:
>         kauditd_print_skb -> kauditd_printk_skb
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  kernel/audit.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Looks good to me, nice catch.  Would you like me to pull this into the
audit tree or are you intending this to get pulled in as part of the
larger patchset somewhere else?

Acked-by: Paul Moore <paul@paul-moore.com>

> diff --git a/kernel/audit.c b/kernel/audit.c
> index 68cee3bc8cfe..0be42cac086b 100644
> --- a/kernel/audit.c
> +++ b/kernel/audit.c
> @@ -523,7 +523,7 @@ static int auditd_set(struct pid *pid, u32 portid, struct net *net)
>  }
>
>  /**
> - * kauditd_print_skb - Print the audit record to the ring buffer
> + * kauditd_printk_skb - Print the audit record to the ring buffer
>   * @skb: audit record
>   *
>   * Whatever the reason, this packet may not make it to the auditd connection
> --
> 2.26.2

-- 
paul moore
www.paul-moore.com

Re: [PATCH v3 51/56] audit: fix a kernel-doc markup

[Mauro Carvalho Chehab]

Em Sun, 25 Oct 2020 18:10:44 -0400
Paul Moore <paul@paul-moore.com> escreveu:

> On Fri, Oct 23, 2020 at 12:33 PM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > typo:
> >         kauditd_print_skb -> kauditd_printk_skb
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  kernel/audit.c | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)  
> 
> Looks good to me, nice catch.  Would you like me to pull this into the
> audit tree or are you intending this to get pulled in as part of the
> larger patchset somewhere else?

Feel free to apply it directly via audit tree.

> 
> Acked-by: Paul Moore <paul@paul-moore.com>

Thanks!
Mauro

> 
> > diff --git a/kernel/audit.c b/kernel/audit.c
> > index 68cee3bc8cfe..0be42cac086b 100644
> > --- a/kernel/audit.c
> > +++ b/kernel/audit.c
> > @@ -523,7 +523,7 @@ static int auditd_set(struct pid *pid, u32 portid, struct net *net)
> >  }
> >
> >  /**
> > - * kauditd_print_skb - Print the audit record to the ring buffer
> > + * kauditd_printk_skb - Print the audit record to the ring buffer
> >   * @skb: audit record
> >   *
> >   * Whatever the reason, this packet may not make it to the auditd connection
> > --
> > 2.26.2  
> 



Thanks,
Mauro

Re: [PATCH v3 01/56] scripts: kernel-doc: fix typedef parsing

[Mauro Carvalho Chehab]

Em Fri, 23 Oct 2020 11:22:26 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Fri, 23 Oct 2020 18:32:48 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> 
> > The include/linux/genalloc.h file defined this typedef:
> > 
> > 	typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
> > 
> > Because it has a type composite of two words (unsigned long),
> > the parser gets the typedef name wrong:
> > 
> > .. c:macro:: long
> > 
> >    **Typedef**: Allocation callback function type definition
> > 
> > Fix the regex in order to accept composite types when
> > defining a typedef for a function pointer.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  scripts/kernel-doc | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index 99cd8418ff8a..311d213ee74d 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -1438,7 +1438,7 @@ sub dump_typedef($$) {
> >      $x =~ s@/\*.*?\*/@@gos;	# strip comments.
> >  
> >      # Parse function prototypes
> > -    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > +    if ($x =~ /typedef\s+(\w+\s*){1,}\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||  
> 
> I sure wish we could find a way to make all these regexes more
> understandable and maintainable.  Reviewing a change like this is ... fun.
> 
> Anyway, it seems to work, but it does now include trailing whitespace in
> the type portion.  So, for example, from include/linux/xarray.h:
> 
>   typedef void (*xa_update_node_t)(struct xa_node *node);
> 
> The type is parsed as "void " where it was "void" before.  The only ill
> effect I can see is that some non-breaking spaces get inserted into the
> HTML output, but perhaps it's worth stripping off that trailing space
> anyway?

Yeah, this is one of the issues. There's another one, tough. While
the above regex recognizes the typedef identifier, it only gets
the last word of "unsigned long", in the case of something like:

	typedef unsigned long (*genpool_algo_t)(unsigned long *map);

Here, we have no option but to use a hidden group, e. g. using
this regex:

	typedef\s+((?:\w+\s*){1,})\(\*\s*(\w\S+)\s*\)\s*\((.*)\);

I'm enclosing a second version with the above. 

Yeah, reviewing it is even funnier, but regex101 can be used to
double-check what the regex is doing:

	https://regex101.com/r/bPTm18/2

Thanks,
Mauro

[PATCH] scripts: kernel-doc: fix typedef parsing

The include/linux/genalloc.h file defined this typedef:

	typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);

Because it has a type composite of two words (unsigned long),
the parser gets the typedef name wrong:

.. c:macro:: long

   **Typedef**: Allocation callback function type definition

Fix the regex in order to accept composite types when
defining a typedef for a function pointer.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99cd8418ff8a..b37f3cf8a331 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1438,13 +1438,14 @@ sub dump_typedef($$) {
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
 
     # Parse function prototypes
-    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
+    if ($x =~ /typedef\s+((?:\w+\s*){1,})\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
 	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
 
 	# Function typedefs
 	$return_type = $1;
 	$declaration_name = $2;
 	my $args = $3;
+	$return_type =~ s/\s+$//;
 
 	create_parameterlist($args, ',', $file, $declaration_name);
 

Re: [PATCH v3 01/56] scripts: kernel-doc: fix typedef parsing

[Mauro Carvalho Chehab]

Em Fri, 23 Oct 2020 11:01:35 -0700
Joe Perches <joe@perches.com> escreveu:

> On Fri, 2020-10-23 at 11:22 -0600, Jonathan Corbet wrote:
> > On Fri, 23 Oct 2020 18:32:48 +0200
> > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> >   
> > > The include/linux/genalloc.h file defined this typedef:
> > > 
> > > 	typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);  
> []
> > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc  
> []
> > >      # Parse function prototypes
> > > -    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > > +    if ($x =~ /typedef\s+(\w+\s*){1,}\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||  
> > 
> > I sure wish we could find a way to make all these regexes more
> > understandable and maintainable.  Reviewing a change like this is ... fun.  
> 
> Perhaps using some of the checkpatch regex definitions like:
> 
> $Type
> $Ident
> $balanced_parens
> 
> would help improve readability.

Well, this can help:


	my $typedef_type = qr { ((?:\w+\s+){1,}) }x;
	my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
	my $typedef_args = qr { \s*\((.*)\); }x;

	my $typedef1 = qr { typedef\s+$typedef_type\($typedef_ident\)$typedef_args }x;
	my $typedef2 = qr { typedef\s+$typedef_type$typedef_ident$typedef_args }x;

	# Parse function typedef prototypes
	if ($x =~ $typedef1 || $x =~ $typedef2) {
		...

But, IMHO, this is as complicated as before, and makes harder
to test the regex outside kernel_doc (like using regex101).

A good thing is that it is easier to see the difference between
the two typedef regexes.

I'll place such optimization on a separate patch. This way, it
should be easier to decide later if this is worth or not.

Also, if we're willing to take such direction, it could make
sense to use the same regexes for matching type, identifier
and arguments inside the functions parser.

> And the regex above doesn't quite work for spacing after typedef.
> The regex should allow space between the open parenthesis and the *
> 
> 	typedef <Type> ( * <Ident> ) (args...);
> 
> And this regex does not find typedefs that use another typedef as <Ident> like:
> 
> arch/s390/include/asm/debug.h:typedef int (debug_header_proc_t) (debug_info_t *id,

True. I guess that, in order to properly handle it, we should use this:

    if ($x =~ /typedef\s+((?:\w+\s+){1,})\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
	$x =~ /typedef\s+((?:\w+\s+){1,})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {

The first check should now parse everything properly:

	https://regex101.com/r/bPTm18/5

And the second regex should also get multi-word types when parenthesis
is not used, like:

	typedef unsigned int debug_header_proc_t (debug_info_t *id, struct debug_view *view, int area,debug_entry_t *entry, char *out_buf);
	typedef unsigned int *debug_header_proc_t (debug_info_t *id, struct debug_view *view, int area,debug_entry_t *entry, char *out_buf);


https://regex101.com/r/Y56X1X/1

Thanks,
Mauro

[PATCH] scripts: kernel-doc: fix typedef parsing

The include/linux/genalloc.h file defined this typedef:

	typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);

Because it has a type composite of two words (unsigned long),
the parser gets the typedef name wrong:

.. c:macro:: long

   **Typedef**: Allocation callback function type definition

Fix the regex in order to accept composite types when
defining a typedef for a function pointer.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99cd8418ff8a..54832618eea0 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1438,13 +1438,14 @@ sub dump_typedef($$) {
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
 
     # Parse function prototypes
-    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
-	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
+    if ($x =~ /typedef\s+((?:\w+\s+){1,})\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
+	$x =~ /typedef\s+((?:\w+\s+){1,})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {
 
 	# Function typedefs
 	$return_type = $1;
 	$declaration_name = $2;
 	my $args = $3;
+	$return_type =~ s/\s+$//;
 
 	create_parameterlist($args, ',', $file, $declaration_name);
 

Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup

[Peter Zijlstra]

On Sat, Oct 24, 2020 at 08:28:27AM +0200, Mauro Carvalho Chehab wrote:
> If the intent is to document the struct and its internal fields,
> this kernel-doc should work:
> 
> 	/**
> 	 * struct refcount_struct - variant of atomic_t specialized for reference counts
> 	 * @refs: atomic_t counter field
> 	 *
> 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> 	 * there. This avoids wrapping the counter and causing 'spurious'
> 	 * use-after-free bugs.
> 	 */
> 
> Which produces this result:

Who cares... :-(

> If you want both, then you would either split struct and typedef, e. g.
> with something like:
> 
> 	/**
> 	 * struct refcount_struct - variant of atomic_t specialized for reference counts
> 	 * @refs: atomic_t counter field
> 	 *
> 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> 	 * there. This avoids wrapping the counter and causing 'spurious'
> 	 * use-after-free bugs.
> 	 */
> 	struct refcount_struct {
> 	        atomic_t refs;
> 	};
> 
> 	/**
> 	 * typedef refcount_t - variant of atomic_t specialized for reference counts
> 	 * @refs: atomic_t counter field
> 	 *
> 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> 	 * there. This avoids wrapping the counter and causing 'spurious'
> 	 * use-after-free bugs.
> 	 */
> 	typedef struct refcount_struct refcount_t;
> 
> Or, you could add the member at the description field. E. g. something
> like this:
> 
> 	/**
> 	 * typedef refcount_t - variant of atomic_t specialized for reference counts
> 	 *
> 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> 	 * there. This avoids wrapping the counter and causing 'spurious'
> 	 * use-after-free bugs.
> 	 *
> 	 * Members:
> 	 *   ``refs``
> 	 *        atomic_t counter field
> 	 */
> 	typedef struct refcount_struct {
> 	        atomic_t refs;
> 	} refcount_t;
> 
> If you want to test it, you can run kernel-doc directly, to see how
> it will parse it. For ReST output, that's the syntax:
> 
> 	./scripts/kernel-doc --sphinx-version 3 include/linux/refcount.h

I'll just go ahead and remove the superfluous * from the comment... It's
trivially clear what is meant. If the stupid tool can't deal with that,
I don't care.

All this wanking about docs and making perfectly fine comments bloody
unreadable shit has to stop.

Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup

[Mauro Carvalho Chehab]

Em Mon, 26 Oct 2020 09:10:59 +0100
Peter Zijlstra <peterz@infradead.org> escreveu:

> On Sat, Oct 24, 2020 at 08:28:27AM +0200, Mauro Carvalho Chehab wrote:
> > If the intent is to document the struct and its internal fields,
> > this kernel-doc should work:
> > 
> > 	/**
> > 	 * struct refcount_struct - variant of atomic_t specialized for reference counts
> > 	 * @refs: atomic_t counter field
> > 	 *
> > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > 	 * use-after-free bugs.
> > 	 */
> > 
> > Which produces this result:  
> 
> Who cares... :-(

Anyone that would need to use refcount_t, instead of atomic_t.

> 
> > If you want both, then you would either split struct and typedef, e. g.
> > with something like:
> > 
> > 	/**
> > 	 * struct refcount_struct - variant of atomic_t specialized for reference counts
> > 	 * @refs: atomic_t counter field
> > 	 *
> > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > 	 * use-after-free bugs.
> > 	 */
> > 	struct refcount_struct {
> > 	        atomic_t refs;
> > 	};
> > 
> > 	/**
> > 	 * typedef refcount_t - variant of atomic_t specialized for reference counts
> > 	 * @refs: atomic_t counter field
> > 	 *
> > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > 	 * use-after-free bugs.
> > 	 */
> > 	typedef struct refcount_struct refcount_t;
> > 
> > Or, you could add the member at the description field. E. g. something
> > like this:
> > 
> > 	/**
> > 	 * typedef refcount_t - variant of atomic_t specialized for reference counts
> > 	 *
> > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > 	 * use-after-free bugs.
> > 	 *
> > 	 * Members:
> > 	 *   ``refs``
> > 	 *        atomic_t counter field
> > 	 */
> > 	typedef struct refcount_struct {
> > 	        atomic_t refs;
> > 	} refcount_t;
> > 
> > If you want to test it, you can run kernel-doc directly, to see how
> > it will parse it. For ReST output, that's the syntax:
> > 
> > 	./scripts/kernel-doc --sphinx-version 3 include/linux/refcount.h  
> 
> I'll just go ahead and remove the superfluous * from the comment... It's
> trivially clear what is meant. If the stupid tool can't deal with that,
> I don't care.

The tool is not that stupid. What's wrong here is that the markup is
asking kernel-doc to document the struct, instead documenting the typedef:

 	/**
 	 * struct refcount_t - variant of atomic_t specialized for reference counts
...

There is no such struct!

Just doing:

	s/struct/typedef/

will do what you intend to document.

Thanks,
Mauro

[PATCH] refcount.h: fix a kernel-doc markup

The kernel-doc markup is wrong: it is asking the tool to document
struct refcount_struct, instead of documenting typedef refcount_t.

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

diff --git a/include/linux/refcount.h b/include/linux/refcount.h
index 0e3ee25eb156..f572c62261a8 100644
--- a/include/linux/refcount.h
+++ b/include/linux/refcount.h
@@ -101,7 +101,7 @@
 struct mutex;
 
 /**
- * struct refcount_t - variant of atomic_t specialized for reference counts
+ * typedef refcount_t - variant of atomic_t specialized for reference counts
  * @refs: atomic_t counter field
  *
  * The counter saturates at REFCOUNT_SATURATED and will not move once

Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup

[Peter Zijlstra]

On Mon, Oct 26, 2020 at 10:16:20AM +0100, Mauro Carvalho Chehab wrote:
> Em Mon, 26 Oct 2020 09:10:59 +0100
> Peter Zijlstra <peterz@infradead.org> escreveu:
> 
> > On Sat, Oct 24, 2020 at 08:28:27AM +0200, Mauro Carvalho Chehab wrote:
> > > If the intent is to document the struct and its internal fields,
> > > this kernel-doc should work:
> > > 
> > > 	/**
> > > 	 * struct refcount_struct - variant of atomic_t specialized for reference counts
> > > 	 * @refs: atomic_t counter field
> > > 	 *
> > > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > > 	 * use-after-free bugs.
> > > 	 */
> > > 
> > > Which produces this result:  
> > 
> > Who cares... :-(
> 
> Anyone that would need to use refcount_t, instead of atomic_t.

They can read the .h file just fine today.

Re: [PATCH v3 53/56] shed: fix kernel-doc markup

[Mauro Carvalho Chehab]

Em Fri, 23 Oct 2020 13:53:41 -0400
Steven Rostedt <rostedt@goodmis.org> escreveu:

> On Fri, 23 Oct 2020 18:33:40 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> 
> > 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  
> 
> The first change looks fine to me, but as I'm getting a new shed delivered
> soon, I originally thought this email was about that delivery!

:-)

> I do have a nit about the second change.
> 
> > diff --git a/kernel/sched/fair.c b/kernel/sched/fair.c
> > index aa4c6227cd6d..94386fcfafcf 100644
> > --- a/kernel/sched/fair.c
> > +++ b/kernel/sched/fair.c
> > @@ -6287,7 +6287,8 @@ static int select_idle_sibling(struct task_struct *p, int prev, int target)
> >  }
> >  
> >  /**
> > - * Amount of capacity of a CPU that is (estimated to be) used by CFS tasks
> > + * cpu_util - Amount of capacity of a CPU that is (estimated to be)
> > + *	used by CFS tasks  
> 
> The description is to be a single line. The line break is ugly, and the 80
> col rule, is more of a guideline, and not something that *has* to be done.
> 
> Either shorten it, or just let it go a little longer.

Agreed, but there are already some other descriptions over there that have
multiple lines[1]:

Anyway, on this specific case, I guess it can be easily shorten to
80 columns without losing anything. Would that work for you?

	/**
	 * cpu_util - Estimates the amount of capacity of a CPU used by CFS tasks.

Regards,
Mauro

[1] like this one:

	/**
	 * calculate_imbalance - Calculate the amount of imbalance present within the
	 *			 groups of a given sched_domain during load balance.
	 * @env: load balance environment
	 * @sds: statistics of the sched_domain whose imbalance is to be calculated.
	 */

Re: [PATCH v3 36/56] locks: fix a typo at a kernel-doc markup

[Jeff Layton]

On Fri, 2020-10-23 at 18:33 +0200, Mauro Carvalho Chehab wrote:
> locks_delete_lock -> locks_delete_block
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  fs/locks.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/fs/locks.c b/fs/locks.c
> index 1f84a03601fe..f3c3ce82a455 100644
> --- a/fs/locks.c
> +++ b/fs/locks.c
> @@ -750,7 +750,7 @@ static void __locks_wake_up_blocks(struct file_lock *blocker)
>  }
>  
>  /**
> - *	locks_delete_lock - stop waiting for a file lock
> + *	locks_delete_block - stop waiting for a file lock
>   *	@waiter: the lock which was waiting
>   *
>   *	lockd/nfsd need to disconnect the lock while working on it.

Thanks, merged. Should make 5.11.

Cheers,
-- 
Jeff Layton <jlayton@kernel.org>

Re: [PATCH v3 48/56] sound: fix kernel-doc markups

[Takashi Iwai]

On Fri, 23 Oct 2020 18:33:35 +0200,
Mauro Carvalho Chehab wrote:
> 
> Kernel-doc markups should use this format:
>         identifier - description
> 
> There is a common comment marked, instead, with kernel-doc
> notation.
> 
> Some identifiers have different names between their prototypes
> and the kernel-doc markup.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Shall I merge this through sound git tree?

Or if this goes via doc tree, feel free to take my ack
  Reviewed-by: Takashi Iwai <tiwai@suse.de>


thanks,

Takashi

Re: [PATCH v3 48/56] sound: fix kernel-doc markups

[Mauro Carvalho Chehab]

Em Mon, 26 Oct 2020 14:46:03 +0100
Takashi Iwai <tiwai@suse.de> escreveu:

> On Fri, 23 Oct 2020 18:33:35 +0200,
> Mauro Carvalho Chehab wrote:
> > 
> > Kernel-doc markups should use this format:
> >         identifier - description
> > 
> > There is a common comment marked, instead, with kernel-doc
> > notation.
> > 
> > Some identifiers have different names between their prototypes
> > and the kernel-doc markup.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> 
> Shall I merge this through sound git tree?
> 
> Or if this goes via doc tree, feel free to take my ack
>   Reviewed-by: Takashi Iwai <tiwai@suse.de>

Thanks for reviewing it!

Feel free to merge it though sound tree.
 
Thanks,
Mauro

Re: [PATCH v3 48/56] sound: fix kernel-doc markups

[Takashi Iwai]

On Mon, 26 Oct 2020 15:14:23 +0100,
Mauro Carvalho Chehab wrote:
> 
> Em Mon, 26 Oct 2020 14:46:03 +0100
> Takashi Iwai <tiwai@suse.de> escreveu:
> 
> > On Fri, 23 Oct 2020 18:33:35 +0200,
> > Mauro Carvalho Chehab wrote:
> > > 
> > > Kernel-doc markups should use this format:
> > >         identifier - description
> > > 
> > > There is a common comment marked, instead, with kernel-doc
> > > notation.
> > > 
> > > Some identifiers have different names between their prototypes
> > > and the kernel-doc markup.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>  
> > 
> > Shall I merge this through sound git tree?
> > 
> > Or if this goes via doc tree, feel free to take my ack
> >   Reviewed-by: Takashi Iwai <tiwai@suse.de>
> 
> Thanks for reviewing it!
> 
> Feel free to merge it though sound tree.

OK, applied now.  Thanks!


Takashi

Re: [PATCH v3 28/56] slimbus: fix a kernel-doc markup

[Srinivas Kandagatla]

On 23/10/2020 17:33, Mauro Carvalho Chehab wrote:
> Fix the name of the enum on its kernel-doc markup:
> 	enum slim_ch_aux_fmt -> enum slim_ch_aux_bit_fmt
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>   drivers/slimbus/slimbus.h | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/slimbus/slimbus.h b/drivers/slimbus/slimbus.h
> index c73035915f1d..00a7f112574b 100644
> --- a/drivers/slimbus/slimbus.h
> +++ b/drivers/slimbus/slimbus.h
> @@ -244,7 +244,7 @@ enum slim_ch_data_fmt {
>   };
>   
>   /**
> - * enum slim_ch_aux_fmt: SLIMbus channel Aux Field format IDs according to
> + * enum slim_ch_aux_bit_fmt: SLIMbus channel Aux Field format IDs according to
>    *	Table 63 of SLIMbus Spec 2.0
>    * @SLIM_CH_AUX_FMT_NOT_APPLICABLE: Undefined
>    * @SLIM_CH_AUX_FMT_ZCUV_TUNNEL_IEC60958: ZCUV for tunneling IEC60958
> 

Applied thanks!

srini

Re: [PATCH v3 27/56] scsi: fix some kernel-doc markups

[Martin K. Petersen]

Mauro,

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

Applied to 5.11/scsi-staging, thanks!

-- 
Martin K. Petersen	Oracle Linux Engineering

Re: [PATCH v3 01/56] scripts: kernel-doc: fix typedef parsing

[Joe Perches]

On Mon, 2020-10-26 at 08:03 +0100, Mauro Carvalho Chehab wrote:
[]
> Well, this can help:
> 	my $typedef_type = qr { ((?:\w+\s+){1,}) }x;

unbounded captures are generally bad, I suggest a limit like {1,5}

>     if ($x =~ /typedef\s+((?:\w+\s+){1,})\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> 	$x =~ /typedef\s+((?:\w+\s+){1,})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {
[]
> Fix the regex in order to accept composite types when
> defining a typedef for a function pointer.
[] 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
[]
> @@ -1438,13 +1438,14 @@ sub dump_typedef($$) {
>      $x =~ s@/\*.*?\*/@@gos;	# strip comments.
>  
> 
>      # Parse function prototypes
> -    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> -	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
> +    if ($x =~ /typedef\s+((?:\w+\s+){1,})\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> +	$x =~ /typedef\s+((?:\w+\s+){1,})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {

This typedef does not allow * returns like

	const unsigned char *(*string)(args...);
or
	unsigned char *const(*fn)(args...);
or
	void *(*alloc)(args...);

(not to mention the truly unusual stuff like the typedefs in
 tools/testing/selftests/bpf/progs/btf_dump_test_case_syntax.c)

typedef void (* (*signal_t)(int, void (*)(int)))(int);
typedef char * (*fn_ptr_arr1_t[10])(int **);
typedef char * (* const (* const fn_ptr_arr2_t[5])())(char * (*)(int));

Re: [PATCH v3 31/56] usb: dwc3: fix kernel-doc markups

[Felipe Balbi]

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


Hi Mauro,

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> There is a common comment marked, instead, with kernel-doc
> notation.
>
> Also, some identifiers have different names between their
> prototypes and the kernel-doc markup.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/usb/dwc3/core.c        | 2 +-
>  drivers/usb/dwc3/core.h        | 2 +-
>  drivers/usb/gadget/composite.c | 2 +-
>  drivers/usb/typec/mux.c        | 2 +-
>  include/linux/usb/composite.h  | 2 +-

mind breaking this into 4 commits? One for dwc3, one for
gadget/composite, one for type/mux, and a final for composite.h.

-- 
balbi

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 857 bytes --]

Re: [PATCH v3 21/56] mac80211: fix kernel-doc markups

[Johannes Berg]

On Fri, 2020-10-23 at 18:33 +0200, Mauro Carvalho Chehab 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
> 
> In the specific case of __sta_info_flush(), add a documentation
> for sta_info_flush(), as this one is the one used outside
> sta_info.c.

Are you taking the entire series through some tree, or should I pick up
this patch?

If you're going to take it:

Reviewed-by: Johannes Berg <johannes@sipsolutions.net>

johannes

Re: [PATCH v3 21/56] mac80211: fix kernel-doc markups

[Mauro Carvalho Chehab]

Em Tue, 27 Oct 2020 08:26:20 +0100
Johannes Berg <johannes@sipsolutions.net> escreveu:

> On Fri, 2020-10-23 at 18:33 +0200, Mauro Carvalho Chehab 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
> > 
> > In the specific case of __sta_info_flush(), add a documentation
> > for sta_info_flush(), as this one is the one used outside
> > sta_info.c.  
> 
> Are you taking the entire series through some tree, or should I pick up
> this patch?

Feel free to pick the patch. IMO, this should work better for
those patches, as it should help avoiding potential merge
conflicts.
> 
> If you're going to take it:
> 
> Reviewed-by: Johannes Berg <johannes@sipsolutions.net>

Thanks for reviewing it!

> 
> johannes
> 
> 



Thanks,
Mauro

Re: [PATCH v3 01/56] scripts: kernel-doc: fix typedef parsing

[Mauro Carvalho Chehab]

Em Mon, 26 Oct 2020 20:55:35 -0700
Joe Perches <joe@perches.com> escreveu:

> On Mon, 2020-10-26 at 08:03 +0100, Mauro Carvalho Chehab wrote:
> []
> > Well, this can help:
> > 	my $typedef_type = qr { ((?:\w+\s+){1,}) }x;  
> 
> unbounded captures are generally bad, I suggest a limit like {1,5}

Ok. 5 is likely too low, if "*" starts to be counted as part of the type.
Maybe 8 would be ok.

> 
> >     if ($x =~ /typedef\s+((?:\w+\s+){1,})\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > 	$x =~ /typedef\s+((?:\w+\s+){1,})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {  
> []
> > Fix the regex in order to accept composite types when
> > defining a typedef for a function pointer.  
> [] 
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc  
> []
> > @@ -1438,13 +1438,14 @@ sub dump_typedef($$) {
> >      $x =~ s@/\*.*?\*/@@gos;	# strip comments.
> >  
> > 
> >      # Parse function prototypes
> > -    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > -	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
> > +    if ($x =~ /typedef\s+((?:\w+\s+){1,})\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
> > +	$x =~ /typedef\s+((?:\w+\s+){1,})\s*\*?(\w\S+)\s*\s*\((.*)\);/) {  
> 
> This typedef does not allow * returns like
> 
> 	const unsigned char *(*string)(args...);
> or
> 	unsigned char *const(*fn)(args...);
> or
> 	void *(*alloc)(args...);

Supporting those shouldn't be hard. See enclosed.

> 
> (not to mention the truly unusual stuff like the typedefs in
>  tools/testing/selftests/bpf/progs/btf_dump_test_case_syntax.c)
> 
> typedef void (* (*signal_t)(int, void (*)(int)))(int);
> typedef char * (*fn_ptr_arr1_t[10])(int **);
> typedef char * (* const (* const fn_ptr_arr2_t[5])())(char * (*)(int));

Parsing those using a single regex, though, is a lot more complex.
The logic would likely require some loop or a real lexical
analyzer in order to properly parse it.

In the specific case of userspace tools (and, in special, selftests),
it is probably not worth the effort to add support for C expressions
that only exists there, as those won't likely gain kernel-doc entries
for their source code to become part of the Kernel documentation.

Thanks,
Mauro

[PATH] scripts: kernel-doc: fix typedef parsing

The include/linux/genalloc.h file defined this typedef:

        typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);

Because it has a type composite of two words (unsigned long),
the parser gets the typedef name wrong:

.. c:macro:: long

   **Typedef**: Allocation callback function type definition

Fix the regex in order to accept composite types when
defining a typedef for a function pointer.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99cd8418ff8a..f699cf05d409 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1431,20 +1431,25 @@ 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 prototypes
-    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
-	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
-
-	# Function typedefs
+    # Parse function typedef prototypes
+    if ($x =~ $typedef1 || $x =~ $typedef2) {
 	$return_type = $1;
 	$declaration_name = $2;
 	my $args = $3;
+	$return_type =~ s/^\s+//;
 
 	create_parameterlist($args, ',', $file, $declaration_name);
 

Re: [PATCH v3 40/56] firmware: stratix10-svc: fix kernel-doc markups

[Richard Gong]

Acked-by: Richard Gong <richard.gong@linux.intel.com>

On 10/23/20 11:33 AM, Mauro Carvalho Chehab wrote:
> 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.
> 
> 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
> @@ -6,7 +6,7 @@
>   #ifndef __STRATIX10_SVC_CLIENT_H
>   #define __STRATIX10_SVC_CLIENT_H
>   
> -/**
> +/*
>    * Service layer driver supports client names
>    *
>    * fpga: for FPGA configuration
> @@ -15,7 +15,7 @@
>   #define SVC_CLIENT_FPGA			"fpga"
>   #define SVC_CLIENT_RSU			"rsu"
>   
> -/**
> +/*
>    * Status of the sent command, in bit number
>    *
>    * SVC_STATUS_OK:
> @@ -50,7 +50,7 @@
>   #define SVC_STATUS_ERROR		5
>   #define SVC_STATUS_NO_SUPPORT		6
>   
> -/**
> +/*
>    * Flag bit for COMMAND_RECONFIG
>    *
>    * COMMAND_RECONFIG_FLAG_PARTIAL:
> @@ -58,7 +58,7 @@
>    */
>   #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
> @@ -218,7 +218,7 @@ void stratix10_svc_free_memory(struct stratix10_svc_chan *chan, void *kaddr);
>   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
> 

Re: [PATCH v3 24/56] PNP: fix kernel-doc markups

[Rafael J. Wysocki]

On Fri, Oct 23, 2020 at 6:38 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> It sounds that there were function renames. Update the kernel-doc
> markups accordingly.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/pnp/core.c | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/drivers/pnp/core.c b/drivers/pnp/core.c
> index 3bf18d718975..a50ab002e9e4 100644
> --- a/drivers/pnp/core.c
> +++ b/drivers/pnp/core.c
> @@ -51,7 +51,7 @@ static void pnp_remove_protocol(struct pnp_protocol *protocol)
>  }
>
>  /**
> - * pnp_protocol_register - adds a pnp protocol to the pnp layer
> + * pnp_register_protocol - adds a pnp protocol to the pnp layer
>   * @protocol: pointer to the corresponding pnp_protocol structure
>   *
>   *  Ex protocols: ISAPNP, PNPBIOS, etc
> @@ -91,7 +91,7 @@ int pnp_register_protocol(struct pnp_protocol *protocol)
>  }
>
>  /**
> - * pnp_protocol_unregister - removes a pnp protocol from the pnp layer
> + * pnp_unregister_protocol - removes a pnp protocol from the pnp layer
>   * @protocol: pointer to the corresponding pnp_protocol structure
>   */
>  void pnp_unregister_protocol(struct pnp_protocol *protocol)
> --

Applied as 5.10-rc material, thanks!

Re: [PATCH v3 51/56] audit: fix a kernel-doc markup

[Paul Moore]

On Sun, Oct 25, 2020 at 6:38 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
> Em Sun, 25 Oct 2020 18:10:44 -0400
> Paul Moore <paul@paul-moore.com> escreveu:
>
> > On Fri, Oct 23, 2020 at 12:33 PM Mauro Carvalho Chehab
> > <mchehab+huawei@kernel.org> wrote:
> > >
> > > typo:
> > >         kauditd_print_skb -> kauditd_printk_skb
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > > ---
> > >  kernel/audit.c | 2 +-
> > >  1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > Looks good to me, nice catch.  Would you like me to pull this into the
> > audit tree or are you intending this to get pulled in as part of the
> > larger patchset somewhere else?
>
> Feel free to apply it directly via audit tree.

I just merged it into audit/next, you should see it shortly.  Thanks!

-- 
paul moore
www.paul-moore.com

Re: [PATCH v3 31/56] usb: dwc3: fix kernel-doc markups

[Greg Kroah-Hartman]

On Tue, Oct 27, 2020 at 08:58:47AM +0200, Felipe Balbi wrote:
> 
> Hi Mauro,
> 
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> > There is a common comment marked, instead, with kernel-doc
> > notation.
> >
> > Also, some identifiers have different names between their
> > prototypes and the kernel-doc markup.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  drivers/usb/dwc3/core.c        | 2 +-
> >  drivers/usb/dwc3/core.h        | 2 +-
> >  drivers/usb/gadget/composite.c | 2 +-
> >  drivers/usb/typec/mux.c        | 2 +-
> >  include/linux/usb/composite.h  | 2 +-
> 
> mind breaking this into 4 commits? One for dwc3, one for
> gadget/composite, one for type/mux, and a final for composite.h.

I'll just take these all at once, it's easy enough :)

thanks,

greg k-h

Re: [PATCH v3 31/56] usb: dwc3: fix kernel-doc markups

[Felipe Balbi]

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

Greg Kroah-Hartman <gregkh@linuxfoundation.org> writes:

> On Tue, Oct 27, 2020 at 08:58:47AM +0200, Felipe Balbi wrote:
>> 
>> Hi Mauro,
>> 
>> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>> > There is a common comment marked, instead, with kernel-doc
>> > notation.
>> >
>> > Also, some identifiers have different names between their
>> > prototypes and the kernel-doc markup.
>> >
>> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>> > ---
>> >  drivers/usb/dwc3/core.c        | 2 +-
>> >  drivers/usb/dwc3/core.h        | 2 +-
>> >  drivers/usb/gadget/composite.c | 2 +-
>> >  drivers/usb/typec/mux.c        | 2 +-
>> >  include/linux/usb/composite.h  | 2 +-
>> 
>> mind breaking this into 4 commits? One for dwc3, one for
>> gadget/composite, one for type/mux, and a final for composite.h.
>
> I'll just take these all at once, it's easy enough :)

Sure thing, in that case:

Acked-by: Felipe Balbi <balbi@kernel.org>

-- 
balbi

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 857 bytes --]

Re: [PATCH v3 45/56] iio: fix a kernel-doc markup

[Jonathan Cameron]

On Fri, 23 Oct 2020 18:33:32 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> A function has a different name between their prototype
> and its kernel-doc markup.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Applied to the togreg branch of iio.git.

Thanks,

Jonathan

> ---
>  include/linux/iio/trigger.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/linux/iio/trigger.h b/include/linux/iio/trigger.h
> index cad8325903f9..f930c4ccf378 100644
> --- a/include/linux/iio/trigger.h
> +++ b/include/linux/iio/trigger.h
> @@ -97,7 +97,7 @@ static inline struct iio_trigger *iio_trigger_get(struct iio_trigger *trig)
>  }
>  
>  /**
> - * iio_device_set_drvdata() - Set trigger driver data
> + * iio_trigger_set_drvdata() - Set trigger driver data
>   * @trig: IIO trigger structure
>   * @data: Driver specific data
>   *

Re: [PATCH v3 17/56] mtd: rawnand: fix a kernel-doc markup

[Miquel Raynal]

On Fri, 2020-10-23 at 16:33:04 UTC, 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>

Applied to https://git.kernel.org/pub/scm/linux/kernel/git/mtd/linux.git nand/next, thanks.

Miquel

Re: [PATCH v3 10/56] EDAC: fix some kernel-doc markups

[Borislav Petkov]

On Fri, Oct 23, 2020 at 06:32:57PM +0200, Mauro Carvalho Chehab wrote:
> Kernel-doc markup should use this format:
>         identifier - description
> 
> Also, some enums are using wrong names at the kernel-doc
> markup.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  drivers/edac/edac_device.h | 11 +++++------
>  include/linux/edac.h       |  4 ++--
>  2 files changed, 7 insertions(+), 8 deletions(-)

Applied, thanks.

-- 
Regards/Gruss,
    Boris.

https://people.kernel.org/tglx/notes-about-netiquette

Re: [PATCH v3 38/56] clk: fix a kernel-doc markup

[Stephen Boyd]

Quoting Mauro Carvalho Chehab (2020-10-23 09:33:25)
> clk_get_duty_cycle -> clk_get_scaled_duty_cycle
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---

Applied to clk-next

Re: [PATCH v3 23/56] PCI: fix kernel-doc markups

[Bjorn Helgaas]

On Fri, Oct 23, 2020 at 06:33:10PM +0200, 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>

Applied to pci/misc for v5.11, thanks!

> ---
>  drivers/pci/p2pdma.c     | 10 +++++-----
>  drivers/pci/pci-driver.c |  4 ++--
>  drivers/pci/pci.c        |  2 +-
>  drivers/pci/probe.c      |  4 ++--
>  drivers/pci/slot.c       |  5 +++--
>  5 files changed, 13 insertions(+), 12 deletions(-)
> 
> diff --git a/drivers/pci/p2pdma.c b/drivers/pci/p2pdma.c
> index de1c331dbed4..bace04145c5f 100644
> --- a/drivers/pci/p2pdma.c
> +++ b/drivers/pci/p2pdma.c
> @@ -609,7 +609,7 @@ bool pci_has_p2pmem(struct pci_dev *pdev)
>  EXPORT_SYMBOL_GPL(pci_has_p2pmem);
>  
>  /**
> - * pci_p2pmem_find - find a peer-to-peer DMA memory device compatible with
> + * pci_p2pmem_find_many - find a peer-to-peer DMA memory device compatible with
>   *	the specified list of clients and shortest distance (as determined
>   *	by pci_p2pmem_dma())
>   * @clients: array of devices to check (NULL-terminated)
> @@ -674,7 +674,7 @@ struct pci_dev *pci_p2pmem_find_many(struct device **clients, int num_clients)
>  EXPORT_SYMBOL_GPL(pci_p2pmem_find_many);
>  
>  /**
> - * pci_alloc_p2p_mem - allocate peer-to-peer DMA memory
> + * pci_alloc_p2pmem - allocate peer-to-peer DMA memory
>   * @pdev: the device to allocate memory from
>   * @size: number of bytes to allocate
>   *
> @@ -727,7 +727,7 @@ void pci_free_p2pmem(struct pci_dev *pdev, void *addr, size_t size)
>  EXPORT_SYMBOL_GPL(pci_free_p2pmem);
>  
>  /**
> - * pci_virt_to_bus - return the PCI bus address for a given virtual
> + * pci_p2pmem_virt_to_bus - return the PCI bus address for a given virtual
>   *	address obtained with pci_alloc_p2pmem()
>   * @pdev: the device the memory was allocated from
>   * @addr: address of the memory that was allocated
> @@ -859,7 +859,7 @@ static int __pci_p2pdma_map_sg(struct pci_p2pdma_pagemap *p2p_pgmap,
>  }
>  
>  /**
> - * pci_p2pdma_map_sg - map a PCI peer-to-peer scatterlist for DMA
> + * pci_p2pdma_map_sg_attrs - map a PCI peer-to-peer scatterlist for DMA
>   * @dev: device doing the DMA request
>   * @sg: scatter list to map
>   * @nents: elements in the scatterlist
> @@ -896,7 +896,7 @@ int pci_p2pdma_map_sg_attrs(struct device *dev, struct scatterlist *sg,
>  EXPORT_SYMBOL_GPL(pci_p2pdma_map_sg_attrs);
>  
>  /**
> - * pci_p2pdma_unmap_sg - unmap a PCI peer-to-peer scatterlist that was
> + * pci_p2pdma_unmap_sg_attrs - unmap a PCI peer-to-peer scatterlist that was
>   *	mapped with pci_p2pdma_map_sg()
>   * @dev: device doing the DMA request
>   * @sg: scatter list to map
> diff --git a/drivers/pci/pci-driver.c b/drivers/pci/pci-driver.c
> index 8b587fc97f7b..591ab353844a 100644
> --- a/drivers/pci/pci-driver.c
> +++ b/drivers/pci/pci-driver.c
> @@ -90,7 +90,7 @@ static void pci_free_dynids(struct pci_driver *drv)
>  }
>  
>  /**
> - * store_new_id - sysfs frontend to pci_add_dynid()
> + * new_id_store - sysfs frontend to pci_add_dynid()
>   * @driver: target device driver
>   * @buf: buffer for scanning device ID data
>   * @count: input size
> @@ -158,7 +158,7 @@ static ssize_t new_id_store(struct device_driver *driver, const char *buf,
>  static DRIVER_ATTR_WO(new_id);
>  
>  /**
> - * store_remove_id - remove a PCI device ID from this driver
> + * remove_id_store - remove a PCI device ID from this driver
>   * @driver: target device driver
>   * @buf: buffer for scanning device ID data
>   * @count: input size
> diff --git a/drivers/pci/pci.c b/drivers/pci/pci.c
> index 6d4d5a2f923d..8b9bea8ba751 100644
> --- a/drivers/pci/pci.c
> +++ b/drivers/pci/pci.c
> @@ -3480,7 +3480,7 @@ bool pci_acs_enabled(struct pci_dev *pdev, u16 acs_flags)
>  }
>  
>  /**
> - * pci_acs_path_enable - test ACS flags from start to end in a hierarchy
> + * pci_acs_path_enabled - test ACS flags from start to end in a hierarchy
>   * @start: starting downstream device
>   * @end: ending upstream device or NULL to search to the root bus
>   * @acs_flags: required flags
> diff --git a/drivers/pci/probe.c b/drivers/pci/probe.c
> index 4289030b0fff..eb1ec037f9e7 100644
> --- a/drivers/pci/probe.c
> +++ b/drivers/pci/probe.c
> @@ -165,7 +165,7 @@ static inline unsigned long decode_bar(struct pci_dev *dev, u32 bar)
>  #define PCI_COMMAND_DECODE_ENABLE	(PCI_COMMAND_MEMORY | PCI_COMMAND_IO)
>  
>  /**
> - * pci_read_base - Read a PCI BAR
> + * __pci_read_base - Read a PCI BAR
>   * @dev: the PCI device
>   * @type: type of the BAR
>   * @res: resource buffer to be filled in
> @@ -1612,7 +1612,7 @@ static bool pci_ext_cfg_is_aliased(struct pci_dev *dev)
>  }
>  
>  /**
> - * pci_cfg_space_size - Get the configuration space size of the PCI device
> + * pci_cfg_space_size_ext - Get the configuration space size of the PCI device
>   * @dev: PCI device
>   *
>   * Regular PCI devices have 256 bytes, but PCI-X 2 and PCI Express devices
> diff --git a/drivers/pci/slot.c b/drivers/pci/slot.c
> index 3861505741e6..bcc8b12ce5da 100644
> --- a/drivers/pci/slot.c
> +++ b/drivers/pci/slot.c
> @@ -323,7 +323,7 @@ EXPORT_SYMBOL_GPL(pci_destroy_slot);
>  #if defined(CONFIG_HOTPLUG_PCI) || defined(CONFIG_HOTPLUG_PCI_MODULE)
>  #include <linux/pci_hotplug.h>
>  /**
> - * pci_hp_create_link - create symbolic link to the hotplug driver module.
> + * pci_hp_create_module_link - create symbolic link to the hotplug driver module.
>   * @pci_slot: struct pci_slot
>   *
>   * Helper function for pci_hotplug_core.c to create symbolic link to
> @@ -349,7 +349,8 @@ void pci_hp_create_module_link(struct pci_slot *pci_slot)
>  EXPORT_SYMBOL_GPL(pci_hp_create_module_link);
>  
>  /**
> - * pci_hp_remove_link - remove symbolic link to the hotplug driver module.
> + * pci_hp_remove_module_link - remove symbolic link to the hotplug driver
> + * 	module.
>   * @pci_slot: struct pci_slot
>   *
>   * Helper function for pci_hotplug_core.c to remove symbolic link to
> -- 
> 2.26.2
> 

Re: [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names

[Matthew Wilcox]

On Fri, Oct 23, 2020 at 06:33:43PM +0200, Mauro Carvalho Chehab wrote:
> 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:

I wonder if we could change kernel-doc to be (optionally) less verbose.
If we allowed people to write:

/**
 * Add a value to a refcount.
 * @i: The value to add to the refcount
 * @r: The refcount
 */

and had the kernel-doc script pick up the name of the following function
automatically, would that be an improvement we could all agree on?

Re: [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names

[Jonathan Corbet]

On Thu, 5 Nov 2020 15:00:17 +0000
Matthew Wilcox <willy@infradead.org> wrote:

> I wonder if we could change kernel-doc to be (optionally) less verbose.
> If we allowed people to write:
> 
> /**
>  * Add a value to a refcount.
>  * @i: The value to add to the refcount
>  * @r: The refcount
>  */
> 
> and had the kernel-doc script pick up the name of the following function
> automatically, would that be an improvement we could all agree on?

Given the number of issues Mauro just fixed where the comments had become
separated from the functions they documented, this seems potentially
hazardous...  It seems especially likely to fail with the "change foo() to
__foo() and add a new foo() down below" pattern that is fairly common.

jon

Re: [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names

[Mauro Carvalho Chehab]

Em Thu, 5 Nov 2020 15:00:17 +0000
Matthew Wilcox <willy@infradead.org> escreveu:

> On Fri, Oct 23, 2020 at 06:33:43PM +0200, Mauro Carvalho Chehab wrote:
> > 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:  
> 
> I wonder if we could change kernel-doc to be (optionally) less verbose.
> If we allowed people to write:
> 
> /**
>  * Add a value to a refcount.
>  * @i: The value to add to the refcount
>  * @r: The refcount
>  */
> 
> and had the kernel-doc script pick up the name of the following function
> automatically, would that be an improvement we could all agree on?

Matthew,

As patches are usually generated with -U3, the context lines are
not enough to show if a comment preceding a function is a kernel-doc
markup or a normal comment.

In practice, on some patches at this series, I found real issues
because something else was added between the kernel-doc markup 
and the documented function. 

So, for me, it sounds a bad idea to remove the function name, as
this can be used to detect such issues.

Thanks,
Mauro

Re: [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names

[Matthew Wilcox]

On Thu, Nov 05, 2020 at 08:15:26AM -0700, Jonathan Corbet wrote:
> On Thu, 5 Nov 2020 15:00:17 +0000
> Matthew Wilcox <willy@infradead.org> wrote:
> 
> > I wonder if we could change kernel-doc to be (optionally) less verbose.
> > If we allowed people to write:
> > 
> > /**
> >  * Add a value to a refcount.
> >  * @i: The value to add to the refcount
> >  * @r: The refcount
> >  */
> > 
> > and had the kernel-doc script pick up the name of the following function
> > automatically, would that be an improvement we could all agree on?
> 
> Given the number of issues Mauro just fixed where the comments had become
> separated from the functions they documented, this seems potentially
> hazardous...  It seems especially likely to fail with the "change foo() to
> __foo() and add a new foo() down below" pattern that is fairly common.

Sort of, yes.  The usual case for doing that is where one adds a new
parameter, and kernel-doc will warn about that.  But if the parameters
stay the same (eg refcount_add takes a lock and __refcount_add assumes
the lock is already held), then you've got documentation of __refcount_add
and no documentation of refcount_add() ... and it's probably still _true_
documentation, just not as useful.