* [PATCH] docs: xforms_lists: handle __cacheline_group_{begin,end}_aligned()
@ 2026-11-07 18:33 Prateekshit Jaiswal via B4 Relay
2026-11-07 19:03 ` Randy Dunlap
0 siblings, 1 reply; 2+ messages in thread
From: Prateekshit Jaiswal via B4 Relay @ 2026-11-07 18:33 UTC (permalink / raw)
To: Jonathan Corbet, Shuah Khan, Randy Dunlap, Mauro Carvalho Chehab
Cc: linux-doc, linux-kernel, Prateekshit Jaiswal
From: Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>
kernel-doc treats each __cacheline_group_{begin,end}_aligned() call as
an undescribed struct member:
Warning: drivers/net/ethernet/intel/idpf/idpf_txrx.h:436 struct member '__cacheline_group_begin_aligned(read_mostly' not described in 'idpf_q_vector'
Those markers are defined in include/linux/cache.h. A former special
case in push_parameter() dropped any member whose name contained
"__cacheline_group", which covered both the plain and _aligned forms.
Commit 8b00d6fe9696 ("docs: kdoc: trim __cacheline_group_* with the
other annotations") replaced that with a transform that only matches
__cacheline_group_begin() and __cacheline_group_end().
The pattern kept that shape when it later moved to CMatch, which
requires a word boundary right after the name. Since "_aligned"
continues the identifier, the suffix still cannot match.
Make the suffix optional, keep the copy of the rule in test_cmatch.py
in sync, and add a kdoc-test.yaml case based on struct idpf_q_vector
that fails without this change. The expected definition still has the
lone ';' that each stripped marker leaves behind, as the unaligned
markers already do.
Running "kernel-doc -none -Wall" over every file with kernel-doc
comments on docs-next, this removes 34 distinct warnings, all in
idpf_txrx.h, and adds none.
The problem was found, and the fix and test drafted, with the help of
an AI coding assistant (Claude Code); I have reviewed and tested the
result.
Fixes: 8b00d6fe9696 ("docs: kdoc: trim __cacheline_group_* with the other annotations")
Signed-off-by: Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>
---
Testing:
- tools/unittests/run.py: all 125 tests pass; the new test fails when
only the xforms_lists.py change is reverted.
- kernel-doc -none -Wall over all files with kernel-doc comments,
before and after: 34 warnings removed, none added.
This is based on docs-next. In linux-next, the kspp tree adds
__require_explicit_initialization to struct_xforms three lines above
the changed one, so the context differs there; the patch still applies
with reduced context and the resolution is trivial.
The lone ';' left in the rendered definition (also seen today for the
plain markers, e.g. struct net_device) appeared with commit 7538df7a2d7d
("docs: xforms_lists: use CMatch for all identifiers"). It is left for
a separate change, which would then also update the new test.
---
tools/lib/python/kdoc/xforms_lists.py | 2 +-
tools/unittests/kdoc-test.yaml | 72 +++++++++++++++++++++++++++++++++++
tools/unittests/test_cmatch.py | 2 +-
3 files changed, 74 insertions(+), 2 deletions(-)
diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
index db23fb650ea8..fa380055191c 100644
--- a/tools/lib/python/kdoc/xforms_lists.py
+++ b/tools/lib/python/kdoc/xforms_lists.py
@@ -38,7 +38,7 @@ class CTransforms:
(CMatch("__rcu"), ""),
(CMatch("____cacheline_aligned_in_smp"), ""),
(CMatch("____cacheline_aligned"), ""),
- (CMatch("__cacheline_group_(?:begin|end)"), ""),
+ (CMatch("__cacheline_group_(?:begin|end)(?:_aligned)?"), ""),
(CMatch("__ETHTOOL_DECLARE_LINK_MODE_MASK"), r"DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)"),
(CMatch("DECLARE_PHY_INTERFACE_MASK",),r"DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)"),
(CMatch("DECLARE_BITMAP"), r"unsigned long \1[BITS_TO_LONGS(\2)]"),
diff --git a/tools/unittests/kdoc-test.yaml b/tools/unittests/kdoc-test.yaml
index 14d36daa1bba..da396f975cb5 100644
--- a/tools/unittests/kdoc-test.yaml
+++ b/tools/unittests/kdoc-test.yaml
@@ -1696,3 +1696,75 @@ tests:
``spinlock_t *lock``
the spinlock
+- name: struct_cacheline_group_aligned
+ description: "Strip __cacheline_group_{begin,end}_aligned() markers from a struct"
+ fname: drivers/net/ethernet/intel/idpf/idpf_txrx.h
+ source: |
+ /**
+ * struct idpf_q_vector
+ * @vport: Vport back pointer
+ * @num_rxq: Number of RX queues
+ * @napi: napi handler
+ * @v_idx: Vector index
+ */
+ struct idpf_q_vector {
+ __cacheline_group_begin_aligned(read_mostly);
+ struct idpf_vport *vport;
+
+ u16 num_rxq;
+ __cacheline_group_end_aligned(read_mostly);
+
+ __cacheline_group_begin_aligned(read_write);
+ struct napi_struct napi;
+ __cacheline_group_end_aligned(read_write);
+
+ __cacheline_group_begin_aligned(cold);
+ u16 v_idx;
+
+ __cacheline_group_end_aligned(cold);
+ };
+ expected:
+ - kdoc_item:
+ name: idpf_q_vector
+ type: struct
+ declaration_start_line: 1
+ sections: {}
+ sections_start_lines: {}
+ parameterlist:
+ - vport
+ - num_rxq
+ - napi
+ - v_idx
+ parameterdesc_start_lines:
+ vport: 2
+ num_rxq: 3
+ napi: 4
+ v_idx: 5
+ parameterdescs:
+ vport: |
+ Vport back pointer
+ num_rxq: |
+ Number of RX queues
+ napi: |
+ napi handler
+ v_idx: |
+ Vector index
+ parametertypes:
+ vport: struct idpf_vport *vport
+ num_rxq: u16 num_rxq
+ napi: struct napi_struct napi
+ v_idx: u16 v_idx
+ warnings: []
+ other_stuff:
+ definition: |
+ ;
+ struct idpf_vport *vport;
+ u16 num_rxq;
+ ;
+ ;
+ struct napi_struct napi;
+ ;
+ ;
+ u16 v_idx;
+ ;
+ purpose: ''
diff --git a/tools/unittests/test_cmatch.py b/tools/unittests/test_cmatch.py
index 109141cd2ab8..02d63a51c05e 100755
--- a/tools/unittests/test_cmatch.py
+++ b/tools/unittests/test_cmatch.py
@@ -324,7 +324,7 @@ class TestSubWithLocalXforms(TestCaseDiff):
(CMatch('__guarded_by'), ' '),
(CMatch('__pt_guarded_by'), ' '),
- (CMatch('__cacheline_group_(begin|end)'), ''),
+ (CMatch('__cacheline_group_(begin|end)(_aligned)?'), ''),
(CMatch('struct_group'), r'\2'),
(CMatch('struct_group_attr'), r'\3'),
---
base-commit: 2649344d20dfb13e30b560f06138229d8e40350a
change-id: 20261107-kdoc-cacheline-aligned-75f1ad0a8c14
Best regards,
--
Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>
^ permalink raw reply [flat|nested] 2+ messages in thread
* Re: [PATCH] docs: xforms_lists: handle __cacheline_group_{begin,end}_aligned()
2026-11-07 18:33 [PATCH] docs: xforms_lists: handle __cacheline_group_{begin,end}_aligned() Prateekshit Jaiswal via B4 Relay
@ 2026-11-07 19:03 ` Randy Dunlap
0 siblings, 0 replies; 2+ messages in thread
From: Randy Dunlap @ 2026-11-07 19:03 UTC (permalink / raw)
To: prateekshitjaiswal73, Jonathan Corbet, Shuah Khan, Mauro Carvalho Chehab
Cc: linux-doc, linux-kernel
On 11/7/26 10:33 AM, Prateekshit Jaiswal via B4 Relay wrote:
> From: Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>
>
> kernel-doc treats each __cacheline_group_{begin,end}_aligned() call as
> an undescribed struct member:
>
> Warning: drivers/net/ethernet/intel/idpf/idpf_txrx.h:436 struct member '__cacheline_group_begin_aligned(read_mostly' not described in 'idpf_q_vector'
>
> Those markers are defined in include/linux/cache.h. A former special
> case in push_parameter() dropped any member whose name contained
> "__cacheline_group", which covered both the plain and _aligned forms.
> Commit 8b00d6fe9696 ("docs: kdoc: trim __cacheline_group_* with the
> other annotations") replaced that with a transform that only matches
> __cacheline_group_begin() and __cacheline_group_end().
>
> The pattern kept that shape when it later moved to CMatch, which
> requires a word boundary right after the name. Since "_aligned"
> continues the identifier, the suffix still cannot match.
>
> Make the suffix optional, keep the copy of the rule in test_cmatch.py
> in sync, and add a kdoc-test.yaml case based on struct idpf_q_vector
> that fails without this change. The expected definition still has the
> lone ';' that each stripped marker leaves behind, as the unaligned
> markers already do.
>
> Running "kernel-doc -none -Wall" over every file with kernel-doc
> comments on docs-next, this removes 34 distinct warnings, all in
> idpf_txrx.h, and adds none.
>
> The problem was found, and the fix and test drafted, with the help of
> an AI coding assistant (Claude Code); I have reviewed and tested the
> result.
>
> Fixes: 8b00d6fe9696 ("docs: kdoc: trim __cacheline_group_* with the other annotations")
> Signed-off-by: Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Thanks.
> ---
> Testing:
> - tools/unittests/run.py: all 125 tests pass; the new test fails when
> only the xforms_lists.py change is reverted.
> - kernel-doc -none -Wall over all files with kernel-doc comments,
> before and after: 34 warnings removed, none added.
>
> This is based on docs-next. In linux-next, the kspp tree adds
> __require_explicit_initialization to struct_xforms three lines above
> the changed one, so the context differs there; the patch still applies
> with reduced context and the resolution is trivial.
>
> The lone ';' left in the rendered definition (also seen today for the
> plain markers, e.g. struct net_device) appeared with commit 7538df7a2d7d
> ("docs: xforms_lists: use CMatch for all identifiers"). It is left for
> a separate change, which would then also update the new test.
> ---
> tools/lib/python/kdoc/xforms_lists.py | 2 +-
> tools/unittests/kdoc-test.yaml | 72 +++++++++++++++++++++++++++++++++++
> tools/unittests/test_cmatch.py | 2 +-
> 3 files changed, 74 insertions(+), 2 deletions(-)
>
> diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
> index db23fb650ea8..fa380055191c 100644
> --- a/tools/lib/python/kdoc/xforms_lists.py
> +++ b/tools/lib/python/kdoc/xforms_lists.py
> @@ -38,7 +38,7 @@ class CTransforms:
> (CMatch("__rcu"), ""),
> (CMatch("____cacheline_aligned_in_smp"), ""),
> (CMatch("____cacheline_aligned"), ""),
> - (CMatch("__cacheline_group_(?:begin|end)"), ""),
> + (CMatch("__cacheline_group_(?:begin|end)(?:_aligned)?"), ""),
> (CMatch("__ETHTOOL_DECLARE_LINK_MODE_MASK"), r"DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)"),
> (CMatch("DECLARE_PHY_INTERFACE_MASK",),r"DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)"),
> (CMatch("DECLARE_BITMAP"), r"unsigned long \1[BITS_TO_LONGS(\2)]"),
> diff --git a/tools/unittests/kdoc-test.yaml b/tools/unittests/kdoc-test.yaml
> index 14d36daa1bba..da396f975cb5 100644
> --- a/tools/unittests/kdoc-test.yaml
> +++ b/tools/unittests/kdoc-test.yaml
> @@ -1696,3 +1696,75 @@ tests:
>
> ``spinlock_t *lock``
> the spinlock
> +- name: struct_cacheline_group_aligned
> + description: "Strip __cacheline_group_{begin,end}_aligned() markers from a struct"
> + fname: drivers/net/ethernet/intel/idpf/idpf_txrx.h
> + source: |
> + /**
> + * struct idpf_q_vector
> + * @vport: Vport back pointer
> + * @num_rxq: Number of RX queues
> + * @napi: napi handler
> + * @v_idx: Vector index
> + */
> + struct idpf_q_vector {
> + __cacheline_group_begin_aligned(read_mostly);
> + struct idpf_vport *vport;
> +
> + u16 num_rxq;
> + __cacheline_group_end_aligned(read_mostly);
> +
> + __cacheline_group_begin_aligned(read_write);
> + struct napi_struct napi;
> + __cacheline_group_end_aligned(read_write);
> +
> + __cacheline_group_begin_aligned(cold);
> + u16 v_idx;
> +
> + __cacheline_group_end_aligned(cold);
> + };
> + expected:
> + - kdoc_item:
> + name: idpf_q_vector
> + type: struct
> + declaration_start_line: 1
> + sections: {}
> + sections_start_lines: {}
> + parameterlist:
> + - vport
> + - num_rxq
> + - napi
> + - v_idx
> + parameterdesc_start_lines:
> + vport: 2
> + num_rxq: 3
> + napi: 4
> + v_idx: 5
> + parameterdescs:
> + vport: |
> + Vport back pointer
> + num_rxq: |
> + Number of RX queues
> + napi: |
> + napi handler
> + v_idx: |
> + Vector index
> + parametertypes:
> + vport: struct idpf_vport *vport
> + num_rxq: u16 num_rxq
> + napi: struct napi_struct napi
> + v_idx: u16 v_idx
> + warnings: []
> + other_stuff:
> + definition: |
> + ;
> + struct idpf_vport *vport;
> + u16 num_rxq;
> + ;
> + ;
> + struct napi_struct napi;
> + ;
> + ;
> + u16 v_idx;
> + ;
> + purpose: ''
> diff --git a/tools/unittests/test_cmatch.py b/tools/unittests/test_cmatch.py
> index 109141cd2ab8..02d63a51c05e 100755
> --- a/tools/unittests/test_cmatch.py
> +++ b/tools/unittests/test_cmatch.py
> @@ -324,7 +324,7 @@ class TestSubWithLocalXforms(TestCaseDiff):
> (CMatch('__guarded_by'), ' '),
> (CMatch('__pt_guarded_by'), ' '),
>
> - (CMatch('__cacheline_group_(begin|end)'), ''),
> + (CMatch('__cacheline_group_(begin|end)(_aligned)?'), ''),
>
> (CMatch('struct_group'), r'\2'),
> (CMatch('struct_group_attr'), r'\3'),
>
> ---
> base-commit: 2649344d20dfb13e30b560f06138229d8e40350a
> change-id: 20261107-kdoc-cacheline-aligned-75f1ad0a8c14
>
> Best regards,
--
~Randy
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2026-11-07 19:03 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2026-11-07 18:33 [PATCH] docs: xforms_lists: handle __cacheline_group_{begin,end}_aligned() Prateekshit Jaiswal via B4 Relay
2026-11-07 19:03 ` Randy Dunlap
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®