Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: xforms_lists: use CMatch for all identifiers
CMatch is lexically correct and replaces only identifiers,
which is exactly where macro transformations happen.
Use it to make the output safer and ensure that all arguments
will be parsed the right way, even on complex cases.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <86d4a07ff0e054207747fabf38d6bb261b52b5fa.1773770483.git.mchehab+huawei@kernel.org>
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
7538df7a
79d881be
+79
-80
+79
-80
tools/lib/python/kdoc/xforms_lists.py
+79
-80
tools/lib/python/kdoc/xforms_lists.py
···
7
7
from kdoc.kdoc_re import KernRe
8
8
from kdoc.c_lex import CMatch, CTokenizer
9
9
10
-
struct_args_pattern = r'([^,)]+)'
10
+
struct_args_pattern = r"([^,)]+)"
11
+
11
12
12
13
class CTransforms:
13
14
"""
···
25
24
26
25
#: Transforms for structs and unions.
27
26
struct_xforms = [
28
-
# Strip attributes
29
-
(KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", flags=re.I | re.S, cache=False), ' '),
30
-
(KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '),
31
-
(KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '),
32
-
(KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '),
33
-
(KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ' '),
34
-
(KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ' '),
35
-
(KernRe(r'\s*__packed\s*', re.S), ' '),
36
-
(KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '),
37
-
(KernRe(r'\s*__private', re.S), ' '),
38
-
(KernRe(r'\s*__rcu', re.S), ' '),
39
-
(KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '),
40
-
(KernRe(r'\s*____cacheline_aligned', re.S), ' '),
41
-
(KernRe(r'\s*__cacheline_group_(begin|end)\([^\)]+\);'), ''),
42
-
(KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re.S),
43
-
r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'),
44
-
(KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)', re.S),
45
-
r'DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'),
46
-
(KernRe(r'DECLARE_BITMAP\s*\(' + struct_args_pattern + r',\s*' + struct_args_pattern + r'\)',
47
-
re.S), r'unsigned long \1[BITS_TO_LONGS(\2)]'),
48
-
(KernRe(r'DECLARE_HASHTABLE\s*\(' + struct_args_pattern + r',\s*' + struct_args_pattern + r'\)',
49
-
re.S), r'unsigned long \1[1 << ((\2) - 1)]'),
50
-
(KernRe(r'DECLARE_KFIFO\s*\(' + struct_args_pattern + r',\s*' + struct_args_pattern +
51
-
r',\s*' + struct_args_pattern + r'\)', re.S), r'\2 *\1'),
52
-
(KernRe(r'DECLARE_KFIFO_PTR\s*\(' + struct_args_pattern + r',\s*' +
53
-
struct_args_pattern + r'\)', re.S), r'\2 *\1'),
54
-
(KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\s*\(' + struct_args_pattern + r',\s*' +
55
-
struct_args_pattern + r'\)', re.S), r'\1 \2[]'),
56
-
(KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', re.S), r'dma_addr_t \1'),
57
-
(KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re.S), r'__u32 \1'),
58
-
(KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1; u64 \1_array[VIRTIO_FEATURES_U64S]; }'),
59
-
60
-
(CMatch(r"__cond_acquires"), ""),
61
-
(CMatch(r"__cond_releases"), ""),
62
-
(CMatch(r"__acquires"), ""),
63
-
(CMatch(r"__releases"), ""),
64
-
(CMatch(r"__must_hold"), ""),
65
-
(CMatch(r"__must_not_hold"), ""),
66
-
(CMatch(r"__must_hold_shared"), ""),
67
-
(CMatch(r"__cond_acquires_shared"), ""),
68
-
(CMatch(r"__acquires_shared"), ""),
69
-
(CMatch(r"__releases_shared"), ""),
27
+
(CMatch("__attribute__"), ""),
28
+
(CMatch("__aligned"), ""),
29
+
(CMatch("__counted_by"), ""),
30
+
(CMatch("__counted_by_(le|be)"), ""),
31
+
(CMatch("__guarded_by"), ""),
32
+
(CMatch("__pt_guarded_by"), ""),
33
+
(CMatch("__packed"), ""),
34
+
(CMatch("CRYPTO_MINALIGN_ATTR"), ""),
35
+
(CMatch("__private"), ""),
36
+
(CMatch("__rcu"), ""),
37
+
(CMatch("____cacheline_aligned_in_smp"), ""),
38
+
(CMatch("____cacheline_aligned"), ""),
39
+
(CMatch("__cacheline_group_(?:begin|end)"), ""),
40
+
(CMatch("__ETHTOOL_DECLARE_LINK_MODE_MASK"), r"DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)"),
41
+
(CMatch("DECLARE_PHY_INTERFACE_MASK",),r"DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)"),
42
+
(CMatch("DECLARE_BITMAP"), r"unsigned long \1[BITS_TO_LONGS(\2)]"),
43
+
(CMatch("DECLARE_HASHTABLE"), r"unsigned long \1[1 << ((\2) - 1)]"),
44
+
(CMatch("DECLARE_KFIFO"), r"\2 *\1"),
45
+
(CMatch("DECLARE_KFIFO_PTR"), r"\2 *\1"),
46
+
(CMatch("(?:__)?DECLARE_FLEX_ARRAY"), r"\1 \2[]"),
47
+
(CMatch("DEFINE_DMA_UNMAP_ADDR"), r"dma_addr_t \1"),
48
+
(CMatch("DEFINE_DMA_UNMAP_LEN"), r"__u32 \1"),
49
+
(CMatch("VIRTIO_DECLARE_FEATURES"), r"union { u64 \1; u64 \1_array[VIRTIO_FEATURES_U64S]; }"),
50
+
(CMatch("__cond_acquires"), ""),
51
+
(CMatch("__cond_releases"), ""),
52
+
(CMatch("__acquires"), ""),
53
+
(CMatch("__releases"), ""),
54
+
(CMatch("__must_hold"), ""),
55
+
(CMatch("__must_not_hold"), ""),
56
+
(CMatch("__must_hold_shared"), ""),
57
+
(CMatch("__cond_acquires_shared"), ""),
58
+
(CMatch("__acquires_shared"), ""),
59
+
(CMatch("__releases_shared"), ""),
60
+
(CMatch("__attribute__"), ""),
70
61
71
62
#
72
63
# Macro __struct_group() creates an union with an anonymous
···
66
73
# need one of those at kernel-doc, as we won't be documenting the same
67
74
# members twice.
68
75
#
69
-
(CMatch('struct_group'), r'struct { \2+ };'),
70
-
(CMatch('struct_group_attr'), r'struct { \3+ };'),
71
-
(CMatch('struct_group_tagged'), r'struct { \3+ };'),
72
-
(CMatch('__struct_group'), r'struct { \4+ };'),
73
-
76
+
(CMatch("struct_group"), r"struct { \2+ };"),
77
+
(CMatch("struct_group_attr"), r"struct { \3+ };"),
78
+
(CMatch("struct_group_tagged"), r"struct { \3+ };"),
79
+
(CMatch("__struct_group"), r"struct { \4+ };"),
74
80
]
75
81
76
82
#: Transforms for function prototypes.
77
83
function_xforms = [
78
-
(KernRe(r"^static +"), ""),
79
-
(KernRe(r"^extern +"), ""),
80
-
(KernRe(r"^asmlinkage +"), ""),
81
-
(KernRe(r"^inline +"), ""),
82
-
(KernRe(r"^__inline__ +"), ""),
83
-
(KernRe(r"^__inline +"), ""),
84
-
(KernRe(r"^__always_inline +"), ""),
85
-
(KernRe(r"^noinline +"), ""),
86
-
(KernRe(r"^__FORTIFY_INLINE +"), ""),
87
-
(KernRe(r"__init +"), ""),
88
-
(KernRe(r"__init_or_module +"), ""),
89
-
(KernRe(r"__exit +"), ""),
90
-
(KernRe(r"__deprecated +"), ""),
91
-
(KernRe(r"__flatten +"), ""),
92
-
(KernRe(r"__meminit +"), ""),
93
-
(KernRe(r"__must_check +"), ""),
94
-
(KernRe(r"__weak +"), ""),
95
-
(KernRe(r"__sched +"), ""),
96
-
(KernRe(r"_noprof"), ""),
97
-
(KernRe(r"__always_unused *"), ""),
98
-
(KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""),
99
-
(KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""),
100
-
(KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""),
101
-
(KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2"),
102
-
(KernRe(r"__no_context_analysis\s*"), ""),
103
-
(KernRe(r"__attribute_const__ +"), ""),
104
-
(KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+"), ""),
84
+
(CMatch("static"), ""),
85
+
(CMatch("extern"), ""),
86
+
(CMatch("asmlinkage"), ""),
87
+
(CMatch("inline"), ""),
88
+
(CMatch("__inline__"), ""),
89
+
(CMatch("__inline"), ""),
90
+
(CMatch("__always_inline"), ""),
91
+
(CMatch("noinline"), ""),
92
+
(CMatch("__FORTIFY_INLINE"), ""),
93
+
(CMatch("__init"), ""),
94
+
(CMatch("__init_or_module"), ""),
95
+
(CMatch("__exit"), ""),
96
+
(CMatch("__deprecated"), ""),
97
+
(CMatch("__flatten"), ""),
98
+
(CMatch("__meminit"), ""),
99
+
(CMatch("__must_check"), ""),
100
+
(CMatch("__weak"), ""),
101
+
(CMatch("__sched"), ""),
102
+
(CMatch("__always_unused"), ""),
103
+
(CMatch("__printf"), ""),
104
+
(CMatch("__(?:re)?alloc_size"), ""),
105
+
(CMatch("__diagnose_as"), ""),
106
+
(CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"),
107
+
(CMatch("__no_context_analysis"), ""),
108
+
(CMatch("__attribute_const__"), ""),
109
+
(CMatch("__attribute__"), ""),
110
+
111
+
#
112
+
# HACK: this is similar to process_export() hack. It is meant to
113
+
# drop _noproof from function name. See for instance:
114
+
# ahash_request_alloc kernel-doc declaration at include/crypto/hash.h.
115
+
#
116
+
(KernRe("_noprof"), ""),
105
117
]
106
118
107
119
#: Transforms for variable prototypes.
108
120
var_xforms = [
109
-
(KernRe(r"__read_mostly"), ""),
110
-
(KernRe(r"__ro_after_init"), ""),
111
-
(KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ""),
112
-
(KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ""),
113
-
(KernRe(r"LIST_HEAD\(([\w_]+)\)"), r"struct list_head \1"),
121
+
(CMatch("__read_mostly"), ""),
122
+
(CMatch("__ro_after_init"), ""),
123
+
(CMatch("__guarded_by"), ""),
124
+
(CMatch("__pt_guarded_by"), ""),
125
+
(CMatch("LIST_HEAD"), r"struct list_head \1"),
126
+
114
127
(KernRe(r"(?://.*)$"), ""),
115
128
(KernRe(r"(?:/\*.*\*/)"), ""),
116
129
(KernRe(r";$"), ""),