Merge tag 'timers-v7.3-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/daniel.lezcano/linux into timers/clocksource

  - Use designated initializers for sh_mtu2, sh_cmt, and sh_tmu, and
    drop the unused initializer in the platform_device_id table for
    sh_mtu2 (Uwe Kleine-König)

  - Remove redundant dev_err()/dev_err_probe() messages when
    devm_request_*_irq() fails, as the helper already logs an error
    message (Pan Chuang)

  - Fix a boot hang on Allwinner D1 when a forced minimum delta is used
    with the sun4i timer (Felix Yan)

  - Fix an IRQ leak in the cpuhp_setup_state() error path by freeing the
    IRQ on failure in the NXP PIT driver (WenTao Liang)

  - Fix incorrect unmapping of shared MMIO between the clocksource and
    clockevent drivers. If one of them fails to initialize, the error
    path unmaps the shared MMIO region, leaving the other driver with an
    invalid mapping on clps711x (Guangshuo Li)

  - Make the samsung_pwm driver compatible with PREEMPT_RT by replacing
    regular spinlocks with raw_spinlock_t in atomic contexts (Marek
    Szyprowski)

  - Use __raw_readl() and __raw_writel() instead of ioread32() and
    iowrite32() to support SWAP_IO_SPACE in the rtl-otto driver (Rustam
    Adilov)

  - Fix a missing clk_disable_unprepare() call in the timer
    initialization error path of the Armada driver (Yuho Choi)

Link: https://lore.kernel.org/lkml/75feea31-683d-45a1-87f4-ab045e0152ae@oss.qualcomm.com

2 files changed, 69 insertions, 11 deletions

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index c3f966da533e..2dedda215c22 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -380,9 +380,36 @@ class KernelDoc:
         #
         if dtype == '':
             if param.endswith("..."):
-                if len(param) > 3: # there is a name provided, use that
+                named_variadic = len(param) > 3
+                if named_variadic: # there is a name provided, use that
+                    #
+                    # If the user documented the parameter using the
+                    # ``@name...:`` form, the description is stored in
+                    # parameterdescs under the unstripped key.  Migrate
+                    # it to the stripped key so the user's text is not
+                    # silently dropped during output, and so the new
+                    # excess-parameter check in check_sections() does
+                    # not flag the unstripped key as orphaned.
+                    #
+                    orig = self.entry.parameterdescs.pop(param, None)
                     param = param[:-3]
+                    if orig is not None and \
+                       not self.entry.parameterdescs.get(param):
+                        self.entry.parameterdescs[param] = orig
                 if not self.entry.parameterdescs.get(param):
+                    #
+                    # For a named variadic (e.g. ``args...``), emit the
+                    # standard "not described" warning before auto-filling
+                    # so a missing or mistyped ``@<name>:`` doc tag does
+                    # not go undetected.  The bare ``...`` form has no
+                    # natural name for the user to document and so always
+                    # gets the auto-generated text.
+                    #
+                    if named_variadic and decl_type == 'function':
+                        self.emit_msg(ln,
+                                      f"function parameter '{param}' "
+                                      f"not described in "
+                                      f"'{declaration_name}'")
                     self.entry.parameterdescs[param] = "variable arguments"
 
             elif (not param) or param == "void":
@@ -546,6 +573,31 @@ class KernelDoc:
                 self.emit_msg(ln,
                               f"Excess {dname} '{section}' description in '{decl_name}'")
 
+        #
+        # Check that documented parameter names (from doc comments, including
+        # inline ``/** @member: */`` tags) actually match real members in
+        # the declaration.  This catches mismatched or stale kernel-doc
+        # member tags that don't correspond to any actual struct/union
+        # member or function parameter.
+        #
+        for param_name, desc in self.entry.parameterdescs.items():
+            # Skip auto-generated entries from push_parameter()
+            if desc == self.undescribed:
+                continue
+            if desc in ("no arguments", "anonymous\n", "variable arguments"):
+                continue
+            if param_name.startswith("{unnamed_"):
+                continue
+            if param_name in self.entry.parameterlist:
+                continue
+
+            if decl_type == 'function':
+                dname = f"{decl_type} parameter"
+            else:
+                dname = f"{decl_type} member"
+            self.emit_msg(ln,
+                          f"Excess {dname} '{param_name}' description in '{decl_name}'")
+
     def check_return_section(self, ln, declaration_name, return_type):
         """
         If the function doesn't return void, warns about the lack of a
diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
index f6ea9efb11ae..4251f7c6673a 100644
--- a/tools/lib/python/kdoc/xforms_lists.py
+++ b/tools/lib/python/kdoc/xforms_lists.py
@@ -29,6 +29,7 @@ class CTransforms:
         (CMatch("__aligned"), ""),
         (CMatch("__counted_by"), ""),
         (CMatch("__counted_by_(le|be)"), ""),
+        (CMatch("__counted_by_ptr"), ""),
         (CMatch("__guarded_by"), ""),
         (CMatch("__pt_guarded_by"), ""),
         (CMatch("__packed"), ""),
@@ -48,16 +49,7 @@ class CTransforms:
         (CMatch("DEFINE_DMA_UNMAP_ADDR"), r"dma_addr_t \1"),
         (CMatch("DEFINE_DMA_UNMAP_LEN"), r"__u32 \1"),
         (CMatch("VIRTIO_DECLARE_FEATURES"), r"union { u64 \1; u64 \1_array[VIRTIO_FEATURES_U64S]; }"),
-        (CMatch("__cond_acquires"), ""),
-        (CMatch("__cond_releases"), ""),
-        (CMatch("__acquires"), ""),
-        (CMatch("__releases"), ""),
-        (CMatch("__must_hold"), ""),
-        (CMatch("__must_not_hold"), ""),
-        (CMatch("__must_hold_shared"), ""),
-        (CMatch("__cond_acquires_shared"), ""),
-        (CMatch("__acquires_shared"), ""),
-        (CMatch("__releases_shared"), ""),
+        (CMatch("__SYSFS_FUNCTION_ALTERNATIVE"), r"union { \1+ }"),
         (CMatch("__attribute__"), ""),
 
         #
@@ -93,13 +85,26 @@ class CTransforms:
         (CMatch("__weak"), ""),
         (CMatch("__sched"), ""),
         (CMatch("__always_unused"), ""),
+        (CMatch("__maybe_unused"), ""),
         (CMatch("__printf"), ""),
         (CMatch("__(?:re)?alloc_size"), ""),
         (CMatch("__diagnose_as"), ""),
         (CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"),
+        (CMatch("__cond_acquires"), ""),
+        (CMatch("__cond_releases"), ""),
+        (CMatch("__acquires"), ""),
+        (CMatch("__releases"), ""),
+        (CMatch("__must_hold"), ""),
+        (CMatch("__must_not_hold"), ""),
+        (CMatch("__must_hold_shared"), ""),
+        (CMatch("__cond_acquires_shared"), ""),
+        (CMatch("__acquires_shared"), ""),
+        (CMatch("__releases_shared"), ""),
         (CMatch("__no_context_analysis"), ""),
         (CMatch("__attribute_const__"), ""),
         (CMatch("__attribute__"), ""),
+        (CMatch("STATIC_IFN_KUNIT"), ""),
+        (CMatch("INLINE_IFN_KUNIT"), ""),
 
         #
         # HACK: this is similar to process_export() hack. It is meant to
@@ -116,6 +121,7 @@ class CTransforms:
         (CMatch("__guarded_by"), ""),
         (CMatch("__pt_guarded_by"), ""),
         (CMatch("LIST_HEAD"), r"struct list_head \1"),
+        (CMatch("DECLARE_PER_CPU"), r"\1 \2[PER_CPU]; }"),
 
         (KernRe(r"(?://.*)$"), ""),
         (KernRe(r"(?:/\*.*\*/)"), ""),