From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id A089635CBD7; Mon, 2 Mar 2026 16:41:09 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469669; cv=none; b=YJfV3w/bgGAG4JLOHlnYjQqbFSn5+7mfETNJyaeKhTJKvIhZSiSDuyOrXpwjy1HWBfZ6qRAsdhbhNm4cTriX4nCjwbsPhF8IZW53BR86hTSycqUmLRMKQ/am5gwN2kwOH2AqIZo58i2sV6DRBprVTWQTFuacFSbgV0PdTVHC4SY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469669; c=relaxed/simple; bh=Mq94eCCs+RKATmleknUccsvrIqNogkHHQ1NGR1scPL0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=IjnmaZNyx9YzKDM+5pITQps71U7CuE1hiKumkvXRa9fqpKdwdbl+0hKhcI/6PWaAGDjW4ycOT7oydxSUMbCMiAReqGyf0oZVTIBWQiUEsxL+LWynD0hsiw9oTKBkV357I8RBazD/2G/5blJTifzlI5Q1tgvaP2YJm6Fka3akhx0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=fMgepz2i; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="fMgepz2i" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 70318C19423; Mon, 2 Mar 2026 16:41:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469669; bh=Mq94eCCs+RKATmleknUccsvrIqNogkHHQ1NGR1scPL0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=fMgepz2ijwJ2lQZdNDNyl/x7TVksfnAOjg5d/9XXaeFFNnJY4mPW+RTQDK9BFAp8J RSzo7c1VNJGZsymdwr3Hotm7sbyvt7/++jmjR4bJNjXD9Uzfi4/EGOyVjfqbXRJly4 oVc7v0l2WTZOrg0YRc+ehvx2wu6rgiJdJ1nG6+WMPtU1kgVHRq4nzehLfF6fiZo5qs 4yTuxkcMKvsDcMP28k8oa6kopTamVnNjJwwP0/b4yJQ1/k5Afe6w4WE4K+UO1s4Uzp ozSIStTLFXRk4PTKnqse1CZamCsCc0wvVVpAyWeiCmP7SF2Q1OBICmxWcuhzxsxQE5 PqDLAZon2rz3A== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KQ-000000002x1-3bCs; Mon, 02 Mar 2026 17:41:06 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 01/18] docs: kdoc_re: add support for groups() Date: Mon, 2 Mar 2026 17:40:44 +0100 Message-ID: <20d1a9c77200e28cc2ff1d6122635c43f8ba6a71.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Add an equivalent to re groups() method. This is useful on debug messages. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 0bf9e01cdc57..774dd747ecb0 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -106,6 +106,13 @@ class KernRe: =20 return self.last_match.group(num) =20 + def groups(self): + """ + Returns the group results of the last match + """ + + return self.last_match.groups() + =20 class NestedMatch: """ --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C7261421A18; Mon, 2 Mar 2026 16:41:09 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469669; cv=none; b=Bh/RfsYozysxDo84XKusUOixdK+jeYeXNMOxsUPFqLH1JYf4atwIjyddBwyKLIrmhTV9q6pK8mgLn79pTkyUaBuL1P47Rr6fgtJmYmJVKaDeCABb/Q0zJFAYO9ZC3z9crJspP8ecHRiwEwwg+Oy1VNYoyCCGGCZ6Qt15n/t6zzE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469669; c=relaxed/simple; bh=ZQpmZi3xCboNCaTitC+DH8Zwcl8IPzrA6Uao2EOU9sw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=VBq8NbcaCtnNLzVev8XtOKHZevKw/lbY5A4JVYTarpc8RloOGvTYKxg9hYyvCtbqrbV7KprVz4V+Z4utPlY+ioNTbHA8nRWI2J8tXZGqAiPYeSKBaB6i+U7IHeJTbXWskNKvPfkMwtakOSaphpQYibARc8aAPJIF0AUkyP7hW44= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=sQHhxax3; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="sQHhxax3" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 73F2EC4AF0B; Mon, 2 Mar 2026 16:41:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469669; bh=ZQpmZi3xCboNCaTitC+DH8Zwcl8IPzrA6Uao2EOU9sw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sQHhxax3PqxDrkJcGF7N3lwkkRJFXuymUfD/qU/71MuSufK/xk0y+g3obvNVWkvj1 86RTeWPd+FMUjdYh/hNAkLWuSVqtdGnp/yyXBcKxVte9/CtGDRV4OShEybTvRC2eP5 lGPd4EQdS/gIlyZGX0XuSR1PRMPZGOhHKBOHAnmOD1QcMtXNMbJBui2bY7Vf2ytuuF mQJLU6T76Rl16YdfJTreR4zD1M1J4ai/N4uz6OrhlE30CAwxwZVEXx1K3SEm8oHcGr e8I9alQg3J4XjBSc5J/47RnGNEPW3AJa6L0OOQXdFrHecXD0bU2ktfAIMzJUN0UNrQ zUDhMzCK1yuSg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KR-000000002yF-0Hb0; Mon, 02 Mar 2026 17:41:07 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 02/18] docs: kdoc_re: don't go past the end of a line Date: Mon, 2 Mar 2026 17:40:45 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The logic which checks if the line ends with ";" is currently broken: it may try to read past the buffer. Fix it by checking before trying to access line[pos]. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 774dd747ecb0..6c44fcce0415 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -269,7 +269,7 @@ class NestedMatch: out +=3D new_sub =20 # Drop end ';' if any - if line[pos] =3D=3D ';': + if pos < len(line) and line[pos] =3D=3D ';': pos +=3D 1 =20 cur_pos =3D pos --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C9CD0421EF2; Mon, 2 Mar 2026 16:41:09 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469669; cv=none; b=lh2/GrQkZcC6cLxnFS/FIKIt3/Kk4FHIfFWfwbOfBP+3+Z93aESmmJagPLmDigkJ5rg0fjLtyUc5tZTxF7pvlKVskNJzrJZRIR3rR7bemdCdNkfOnhd4raHs56bs3WVzCzpq27ZVXOSO5663KgUJpb9fMcBH//IgUoRaPgcsc4o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469669; c=relaxed/simple; bh=ftCwoMytpLULQWEXGblskf53KEc3VuT0xZwVGahX9Ic=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=YjHxgcTDXMDhO5lG2gevDPUItTTZw2k+lYrRgv5GDOE35jjwhdd29144YsUF6+MBjbmTPAp1SjJvbsZp5p7TaTHun1U+UAuVLUmSKNhtuS2llLbd7UEMm9O1Fdkt0BiLOlcEFeQFh3qqv2KSwbed4KMcdQAUCbLTN63DEePD9Bc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=KbkcXPGa; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="KbkcXPGa" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 84C30C2BC9E; Mon, 2 Mar 2026 16:41:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469669; bh=ftCwoMytpLULQWEXGblskf53KEc3VuT0xZwVGahX9Ic=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KbkcXPGa8XpCHMjRifGVHpDVmovqOP+blOxiAJt5bjwZzr71L/nyCqg3AelK+AQPl /jVIP27whgnKKVGttZDpkoJQmf+J00s3/GHpBD6dX1BTW2Eh/bLexD1oA2RSV08Nhl btg1W2+VDzfB8KyRpWNmQRO0SE18ytwMW+wF7NF9cLSNTkC1jHsRK5ib8MJE+5/Bem S6JFmqyDhVC2lLX4M7rJ5BaTj1gbwxYeHxBTr1n1lBkDOLTNFwONSWmxnMnf+8JK+l flJ33S9k8iOwjMguVgy6eUIvKW30Qlg9T83pl0HQo6KtpoYh/vDVQ0iqpCZ7r6UG6L aC2iEBBS9iYYw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KR-000000002zS-18sg; Mon, 02 Mar 2026 17:41:07 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 03/18] docs: kdoc_parser: move var transformers to the beginning Date: Mon, 2 Mar 2026 17:40:46 +0100 Message-ID: <491b290252a308f381f88353a3bbe9e2bd1f6a62.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Just like functions and structs had their transform variables placed at the beginning, move variable transforms to there as well. No functional changes. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index ca00695b47b3..68a5aea9175d 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -192,6 +192,18 @@ function_xforms =3D [ (KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+")= , ""), ] =20 +# +# Transforms for variable prototypes +# +var_xforms =3D [ + (KernRe(r"__read_mostly"), ""), + (KernRe(r"__ro_after_init"), ""), + (KernRe(r"(?://.*)$"), ""), + (KernRe(r"(?:/\*.*\*/)"), ""), + (KernRe(r";$"), ""), + (KernRe(r"=3D.*"), ""), +] + # # Ancillary functions # @@ -972,15 +984,6 @@ class KernelDoc: ] OPTIONAL_VAR_ATTR =3D "^(?:" + "|".join(VAR_ATTRIBS) + ")?" =20 - sub_prefixes =3D [ - (KernRe(r"__read_mostly"), ""), - (KernRe(r"__ro_after_init"), ""), - (KernRe(r"(?://.*)$"), ""), - (KernRe(r"(?:/\*.*\*/)"), ""), - (KernRe(r";$"), ""), - (KernRe(r"=3D.*"), ""), - ] - # # Store the full prototype before modifying it # @@ -1004,7 +1007,7 @@ class KernelDoc: # Drop comments and macros to have a pure C prototype # if not declaration_name: - for r, sub in sub_prefixes: + for r, sub in var_xforms: proto =3D r.sub(sub, proto) =20 proto =3D proto.rstrip() --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C73C1421EEC; Mon, 2 Mar 2026 16:41:09 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469669; cv=none; b=P9nvy/Yofgz/d1mw9rL1VRieoQVkOQVFIpVWYUBPk+K8bFnUy5dVm9SQhsNXxm+RTmbAPCNqJyhaN6SVJanRGn59r55NxBVIwH5fyIkvPk/ae3U07YybncL+zPrlkm1E46OI0l0EI503N8wKBjC05uSc9lZa4FJEvsOp1GCqHn8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469669; c=relaxed/simple; bh=l1TnXg9K1HZGJE+MUFeDj5Ao7LGwzZBBWNXmq8OcdpM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=DPju2sZdXjcTxx9YShOi3KJqqo5tI6VdqrXQFcpEi9oPBfgpdFDcT7vwF5apn+v6VjzzbPJjgGwjKRjYS7kPoEU/Tyk7Q5H2j6yriLYCBBNXs8vJ/3Y3qOZY0mk05MLCpPSeS2KTAjMaBsrWO6A4Nc8XD6S7417ny6JjkpdEJ4Y= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=VRbrwor0; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="VRbrwor0" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7CF6FC2BC87; Mon, 2 Mar 2026 16:41:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469669; bh=l1TnXg9K1HZGJE+MUFeDj5Ao7LGwzZBBWNXmq8OcdpM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=VRbrwor0sf65/BAVNyn5/8Bc4uF2uUGQDaoBNcIgYcQ3t1W6cGGfhcoTlPPu6d2l1 I6Tl1oLUwI5O+N/bO/jGoQmrYHR22Trnm32B7DH50NbkB7h/U7JuDBR6udpHM61v4L hBoLwHOnH267kgi6NnM+uHI2QdnsWbE3iJu26qvI+fCquoVetlOv6cD+aiaJ8/M05a s4f/TGhS7TwVTo5feNc+5jlwg4Z88sob3ZG9TSuxdH2zzQPiUZ4AZPh7GEyVKRSCDS lIPLgKVSCocRVTWOXKopFMGyZZrHKIjn7cT4L9hdJVPN95cnsG/ftU80USShkFmSjs jdIbyT2Wi1wxw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KR-00000000311-1z8t; Mon, 02 Mar 2026 17:41:07 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 04/18] docs: kdoc_parser: don't mangle with function defines Date: Mon, 2 Mar 2026 17:40:47 +0100 Message-ID: <8f9854c8ca1c794b6a3fe418f7adbc32aa68b432.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Mangling with #defines is not nice, as we may end removing the macro names, preventing several macros from being properly documented. Also, on defines, we have something like: #define foo(a1, a2, a3, ...) \ /* some real implementation */ The prototype part (first line on this example) won't contain any macros, so no need to apply any regexes on it. With that, move the apply_transforms() logic to ensure that it will be called only on functions. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 68a5aea9175d..9643ffb7584a 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -163,7 +163,7 @@ struct_nested_prefixes =3D [ # # Transforms for function prototypes # -function_xforms =3D [ +function_xforms =3D [ (KernRe(r"^static +"), ""), (KernRe(r"^extern +"), ""), (KernRe(r"^asmlinkage +"), ""), @@ -1066,10 +1066,7 @@ class KernelDoc: found =3D func_macro =3D False return_type =3D '' decl_type =3D 'function' - # - # Apply the initial transformations. - # - prototype =3D apply_transforms(function_xforms, prototype) + # # If we have a macro, remove the "#define" at the front. # @@ -1088,6 +1085,11 @@ class KernelDoc: declaration_name =3D r.group(1) func_macro =3D True found =3D True + else: + # + # Apply the initial transformations. + # + prototype =3D apply_transforms(function_xforms, prototype) =20 # Yes, this truly is vile. We are looking for: # 1. Return type (may be nothing if we're looking at a macro) --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C7483421EED; Mon, 2 Mar 2026 16:41:09 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469669; cv=none; b=Gh+bJXNEg8FGPT2YhS2miAos+Y/Y6w+sT8Ghh+yvcqM0RqI1nARHX6HawUgDEKn46bIol6Wtn1LAPmSuaqaoXmoCwt1aaJYXuqE0b030e+l4ArynW4vxYS5COFrspNURJQWPvO9PYFByXJYlFG4XYhTknRQjSkOXpeTATnUDKK8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469669; c=relaxed/simple; bh=3YzxxHgVjkBet+RBKm4GWxqcg0N/we4EFRl+qm5WAOs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=MpxaK6gqWGCIz9rLCnksvQ02wuTtebmFORb1ZsQq3M/lYr4QDcgKYtCOB/naHwBoSrA3IxGcMu1f8aSUVHwR3PUkuadrIKZsGYb5ajkOJdmue+E16vlLnuAqktI1MnHfi1E7M2aHx34Hg8PLTY4ESXcNx5eWAaoFUCrYIH4qO+I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=hHssqK16; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="hHssqK16" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 82B81C2BCAF; Mon, 2 Mar 2026 16:41:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469669; bh=3YzxxHgVjkBet+RBKm4GWxqcg0N/we4EFRl+qm5WAOs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hHssqK16wou1zOz3yoo/HO9erjhMozloQ4bEl4tLNbPxPwyKeJq6DOCLEiZurlEhX zFWaVC4a5sRcuEjNrVbcn7U56lR0vNhzqWqpa+OBAC6haKtYDVFPnZMwYxAgCSJS+B eh5JsQU3J0Xja1ha+IN0h7188xwZYz4uYkmook3gYroMc7Be1/F06NCEfM00ZoJbxG Gb5oZOkX/1ZXSfczB6hMvjS22hM8C9fl8SULfXAFK4YxcYbe9KcIHmItu8dEBN/uI7 B65+FVNQf9QOOrKRy9B2VVzkGQLlkGlkQTWWo624bk9R3sWpvQNrgE4XsLhocs+vbo BfLM7ZuR5k8fQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KR-0000000032F-2n4B; Mon, 02 Mar 2026 17:41:07 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 05/18] docs: kdoc_parser: fix variable regexes to work with size_t Date: Mon, 2 Mar 2026 17:40:48 +0100 Message-ID: <8230715239929cf9d475ab81ca1df7de65d82d06.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The regular expressions meant to pick variable types are too naive: they forgot that the type word may contain underlines. It also means that we need to change the regex which detects var attributes to handle "const". Co-developed-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 9643ffb7584a..9c9443281c40 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -981,8 +981,9 @@ class KernelDoc: """ VAR_ATTRIBS =3D [ "extern", + "const", ] - OPTIONAL_VAR_ATTR =3D "^(?:" + "|".join(VAR_ATTRIBS) + ")?" + OPTIONAL_VAR_ATTR =3D r"^(?:\b(?:" +"|".join(VAR_ATTRIBS) +r")\b\s= *)*" =20 # # Store the full prototype before modifying it @@ -1018,14 +1019,14 @@ class KernelDoc: =20 default_val =3D None =20 - r=3D KernRe(OPTIONAL_VAR_ATTR + r"\w.*\s+(?:\*+)?([\w_]+)\s*[\d\]\= []*\s*(=3D.*)?") + r=3D KernRe(OPTIONAL_VAR_ATTR + r"[\w_]*\s+(?:\*+)?([\w_]+)\s*[\d\= ]\[]*\s*(=3D.*)?") if r.match(proto): if not declaration_name: declaration_name =3D r.group(1) =20 default_val =3D r.group(2) else: - r=3D KernRe(OPTIONAL_VAR_ATTR + r"(?:\w.*)?\s+(?:\*+)?(?:[\w_]= +)\s*[\d\]\[]*\s*(=3D.*)?") + r=3D KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_]*)?\s+(?:\*+)?(?:[\w= _]+)\s*[\d\]\[]*\s*(=3D.*)?") if r.match(proto): default_val =3D r.group(1) =20 --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 784E7423A77; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469670; cv=none; b=U6+CB8iuf9iyfUiGLlp/9yFKToRheaGU7ZdWas+qqaBah5YlKyp0zUQwBBvsB99+VETBNSfVASba2yZiUl1KiWDHViquc2w5mrxicOJFy9l4TN6yFbESvC7z8qBUw69f6LJaSc81Y8inhuYuM3Pr3Jv3ttrew436gwicNS1F5sQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469670; c=relaxed/simple; bh=JFl/dLUF5g2ndZqfUyzTuu/xxP7qt+WvHToR++nCWEA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=KHFG6oNqmK/TK/W1ga8lutnAg9lK9M+8BxnRk5p2irMJpLVFLyqMRTaBzVNz5IzrkX0FKbjH11NJR8uc4QXoTFL1/v1cQwZRvgUCOZmpCMsKpZNHkXFdh5N6ddRa56lQivaH/XV5QlF+ZyIHEW0XMHNtMsX3z5oEgMzeSsS/K5A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=A24yQteX; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="A24yQteX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3B760C2BC87; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469670; bh=JFl/dLUF5g2ndZqfUyzTuu/xxP7qt+WvHToR++nCWEA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=A24yQteX5U1M5fNAhThvq+29qWdIp5RcIs/U8xTBS7BbN6IGm4HWGo3tgi3SFwz0i NRdbldVsysOfYhiOhgFl773BTWvNPnRnOJmiZpMTUMDBoIkzGAYNPn+z6CnGLFu0qE 4sCSyR2C/mhTePb9OivF9qjq7vYfSNsc/ZJDDigBc/BYCgkEXxuBui0dSNJt9HXu+o DNdZjBDIvPthIcqWY/q/Ch5Ko1AS4oNYwUx5V2kea6uVfvwJZyvn/KrxERk/j9BtQ/ 2vrCGQ8lAX9sOcKirMXJlEyn4HkjqcLnrZjY4/lAzYoKa+qsZfELnRAPH07gzuTAC7 noL9RtqqJVIbQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KR-0000000033S-3anc; Mon, 02 Mar 2026 17:41:07 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 06/18] docs: kdoc_parser: fix the default_value logic for variables Date: Mon, 2 Mar 2026 17:40:49 +0100 Message-ID: <681f18338abd6ae33cb9c15d72bb31a1cba75a9a.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The indentation is wrong for the second regex, which causes problems on variables with defaults. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 9c9443281c40..4bf55244870f 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1027,9 +1027,9 @@ class KernelDoc: default_val =3D r.group(2) else: r=3D KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_]*)?\s+(?:\*+)?(?:[\w= _]+)\s*[\d\]\[]*\s*(=3D.*)?") - if r.match(proto): - default_val =3D r.group(1) =20 + if r.match(proto): + default_val =3D r.group(1) if not declaration_name: self.emit_msg(ln,f"{proto}: can't parse variable") return --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 56F22423A67; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469670; cv=none; b=s6PwT323NaKUHGMkiMuMQ3QZ4hH2C0hcon+f9fjE+bVkaVIivbjx7fXKX7C3j56r9iVuwULUwZJasf2/l5BtLHAYXGzLX/8VdjIVpxw084oUlbmTTb86VU8aIojCWeyTMZfJlFpFvALjyauRtLcSATK6vLkGk9PujK2d4R16/ko= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469670; c=relaxed/simple; bh=Cz/nEycnBHQCO4/w8hm2Eo242zi9lKr/VICMSuqJXdw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=G6ozi6xJTAIn1mBRnLP4svI9mxu4C05khzvoyW9b3pxtJGY405SLJXTDKukXE5PyOD7P81ZbOkkj4foVQBtYclKIn6SAHChvQoeEQjnLIjvIlDKoqYnbsz8XgqdtzaYN8jiN5rnClkgJT7FJjQ2cVqs5giKFv57ynrMuxwfL28Q= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=B5+5UFsv; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="B5+5UFsv" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 35FE3C19423; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469670; bh=Cz/nEycnBHQCO4/w8hm2Eo242zi9lKr/VICMSuqJXdw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=B5+5UFsv2VkRh7U/2I9W1NgiGTA90D1siDOibs+9CWTz/Fqw5pf9CpqFtbEd3OnIu BbJ0UR/zDmcCsN4KqbXlf63g9n98ckb6LKlnNO1dPqMGMxYMrCKY6oo1sFuIVeR4kR ++P8yq8rKOCeNP4WBF1B3j9W0zUsuQSYgYBhlYwuCZ7n5KKgle9CEyJ0Nt36R23KJQ i86QMWtWYwVPrVhhvmI436XHX/oe0/eO1/iawD98vOVypU8e6w/12kaLpsSTaSCVUf 0HE9NcL04TlaIHtG9yiOS5LSjtP2LzNhJnLHUbYgb/nKI3MDow1CDbUvx6YK8BN4GV j3HzXZeElIpIQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KS-0000000034f-0BnH; Mon, 02 Mar 2026 17:41:08 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 07/18] docs: kdoc_parser: don't exclude defaults from prototype Date: Mon, 2 Mar 2026 17:40:50 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab If we do that, the defaults won't be parsed. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 1 - 1 file changed, 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 4bf55244870f..39ff27d421eb 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -201,7 +201,6 @@ var_xforms =3D [ (KernRe(r"(?://.*)$"), ""), (KernRe(r"(?:/\*.*\*/)"), ""), (KernRe(r";$"), ""), - (KernRe(r"=3D.*"), ""), ] =20 # --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 5A93E423A6A; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469670; cv=none; b=uGXPr6byl+IdkdshHijQlvq1H06cbspzzuNadVqF0PLuRu94TWP80L+Vm8JUQ6x6JmDi2gtk/q+bnuQ8r4GIVSjrZ4XZ6/2c12yM0SLZjCBM6Up7qDwdTnVqYvtPlDHNIllZ9LHHqJ+xbd+vNJ5mVJonzPBbvjf/XYV2Utce9bY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469670; c=relaxed/simple; bh=E99JX2x2bb+0GoK4fzDy1ZhSDI4u616jwvyzl9pv/wo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Kd58kSJkOcvT637HVHmydBk7bt0MPP9wk2kUdDBEr7exq94yEHWZsbFJCXhweTrROBRBRrEVFSKt+MNWVY2EPt4Dn5qw4U0qzacn4Q0H/Pjy1QprXoQV/lIE8iNceQG4Y/PZ4Ur36i39UvzZPRtTTCmHJAmED0GYXWueuKpDBM8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=hl47MmHh; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="hl47MmHh" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 34FA3C2BCAF; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469670; bh=E99JX2x2bb+0GoK4fzDy1ZhSDI4u616jwvyzl9pv/wo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hl47MmHh1IluAWUgODvHXYuFVBjWPtk2Sz9KTXqrUqF/shtXoF042UIJIS/NnTSPN MmLmEZMkCG6qJvA5ug0NDNpYXhb30c8mv61y/KH/hoh5XrdleHMqv9w6sn7JO/Z2Y1 /dxEt+c8lXkFGH/vS7o9nLDD8+b82gDmjW5J5z3bvUPdGiuhl344fNLmeYJBWnjw6R VtDDtd1FzKdF0IJtsNTyHGbsn0iViD+jnbcDsXM+/FHs8jZXuWH/xsElidDHVW3Bh2 8wiNhrMwoY3SBmDKOI8vH+47IFRnsQXUksAvm5lw9mKNm5Tfl+w82aweRAWh0CLTrg NeH+o96MI+wNg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KS-0000000035v-0yqk; Mon, 02 Mar 2026 17:41:08 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 08/18] docs: kdoc_parser: fix parser to support multi-word types Date: Mon, 2 Mar 2026 17:40:51 +0100 Message-ID: <544c73a9e670b6fef1828bf4f2ba0de7d29d8675.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The regular expression currently expects a single word for the type, but it may be something like "struct foo". Add support for it. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 39ff27d421eb..22a820d33dc8 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1018,14 +1018,14 @@ class KernelDoc: =20 default_val =3D None =20 - r=3D KernRe(OPTIONAL_VAR_ATTR + r"[\w_]*\s+(?:\*+)?([\w_]+)\s*[\d\= ]\[]*\s*(=3D.*)?") + r=3D KernRe(OPTIONAL_VAR_ATTR + r"\s*[\w_\s]*\s+(?:\*+)?([\w_]+)\s= *[\d\]\[]*\s*(=3D.*)?") if r.match(proto): if not declaration_name: declaration_name =3D r.group(1) =20 default_val =3D r.group(2) else: - r=3D KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_]*)?\s+(?:\*+)?(?:[\w= _]+)\s*[\d\]\[]*\s*(=3D.*)?") + r=3D KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_\s]*)?\s+(?:\*+)?(?:[= \w_]+)\s*[\d\]\[]*\s*(=3D.*)?") =20 if r.match(proto): default_val =3D r.group(1) --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 5A3AD423A68; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469670; cv=none; b=kCayzYc80ElcN16j5Nnty1E9A9ag3rtjiRZToYStU7LX+LKe7yKXBmIG1RsqtAiYnUjVjbcH9OiHKZHNIkSS7AKzwGl66q7tUZT9oylugUirmiqzU2sbsiXDpNVCmeRk07SgaGxLeZGH2xjYpxLjFkKWOtShe9pluXvOK2xQ55E= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469670; c=relaxed/simple; bh=IanSHDFR27HztJ4b5ZTKzFpHQEo73fYniHq3F2749zw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=TWpbWDuGuZZ5/8QE4E4WyTgaYZVJN6nZ1Ujlw5EnWg60aKbBo1YHkgKnGhQ4are26vBgh3iCI1HAbrCfafyIG0aZqhP/m4mI9XYlcweMZ0TdIEKQNT9ZWL09rVGxLa+bB7PQ5aV6IYXoQ1xfH72gQdK7VSbk2k8VQg6egcXrdu0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZT7+QTBe; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="ZT7+QTBe" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 34FDAC4AF09; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469670; bh=IanSHDFR27HztJ4b5ZTKzFpHQEo73fYniHq3F2749zw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZT7+QTBeMyAWLn31f/3W88Q3jWyiihx9g3Jt+vWVBBGSKji6mumLsrKWpfqM6mZwn 6RxEFNInQCI8Hvr91pvHfU+J8KGVIK3ylP2LE7nYt5JIRInhdmWqGgqshsYlksSxZ4 UAYtv1czaqURVogAHWfh0XBE4BDPnwqutd3lbC+8fLX3h5uijX/4B/UN/tF8Y19FiO jfEFzSriFXex1jc/lIRIK1lWfmm442a6p/ZpiOzjHjs11SFR1ZK/HX+f2rQMyl1q0t k+ylNE5ZuVu2Fc9ti/P/4hJrbiELLpYK753jeRViGydSgLmDu/zZTgkCXx8hL1Y+Vu ZVG2AlMP7UcPA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KS-00000000379-1mmd; Mon, 02 Mar 2026 17:41:08 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 09/18] docs: kdoc_parser: add support for LIST_HEAD Date: Mon, 2 Mar 2026 17:40:52 +0100 Message-ID: <8bdfa6ba6002b0a73a83660f0ce7b40e30124552.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Convert LIST_HEAD into struct list_head when handling its prototype. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 22a820d33dc8..1df869061bf3 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -198,6 +198,7 @@ function_xforms =3D [ var_xforms =3D [ (KernRe(r"__read_mostly"), ""), (KernRe(r"__ro_after_init"), ""), + (KernRe(r"LIST_HEAD\(([\w_]+)\)"), r"struct list_head \1"), (KernRe(r"(?://.*)$"), ""), (KernRe(r"(?:/\*.*\*/)"), ""), (KernRe(r";$"), ""), --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id E6AEC425CEE; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469671; cv=none; b=sRCFyU04rXtW/OFRxBUArnZ0I6u0SwqeiYWrccbOuojzbNfd1cFLyWqxKGz056QaZATvjtQ+wiUltYGzFdFuCUkzyj4JX7UQmKsW2GDwmIyO5tgU2wz7QMjcb/SySM2yt/tKV9SbdbIDEvLKExZ1ZgZUNsIIlEVIBjuQY5qtrAU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469671; c=relaxed/simple; bh=61qjPlozwdHGFvs8c7DRWC7o3HB3XcjbiutDDyCkiOs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=lVVZgPi7Kb6LIc3d0SMFIVt6RPiCxuW1Aj283KOtFBVpCFhccWy8yZn3razTk2q+9smeuexLiscuzgohb/21mmPd7POMALLm0MB/m2Upo6zLTTZV3tR6GG5LcmiHcpZJoYEDBBpgspBfg+GTXfYHY6ah6GDJN37MCdvIbFzzS1k= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Xye5RCmi; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="Xye5RCmi" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C3EB5C2BC9E; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469670; bh=61qjPlozwdHGFvs8c7DRWC7o3HB3XcjbiutDDyCkiOs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Xye5RCmi5xwFqa2D1USh3659QwPyNjT0/WYBASKxeORUNAju7/Z1H4E2NG1M/Pmwy Ek5+hnsLejOn9tSf7b+9oSjc8zvcOLH+//Jf4jqQuwhWh1F739hbeC23QabvbKRhz2 MP4Qpv0ED6wS+Rlp7XmxF2gsPheebuVGAq69fInn594/ThojYzeSBdUeWPYcuT2bjo uB/1c40XN6yFivPNDbq97djllR6Ljx6xO81mEsOpLZoYSvIMabct3eZQ6Zu3IAK0Ml YeopJQH8joLiSx3v4XPxNU1fTCSErt3VKwnGhv8WedtqJOyPGP6pDOIwXolup0J8MB 8La2xAcwDYjBQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KS-0000000038M-2b0y; Mon, 02 Mar 2026 17:41:08 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 10/18] docs: kdoc_parser: handle struct member macro VIRTIO_DECLARE_FEATURES(name) Date: Mon, 2 Mar 2026 17:40:53 +0100 Message-ID: <6f62e1f1210e74906fa50f4e937f66f54813661b.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab From: Randy Dunlap Parse the macro VIRTIO_DECLARE_FEATURES(name) and expand it to its definition. These prevents one build warning: WARNING: include/linux/virtio.h:188 struct member 'VIRTIO_DECLARE_FEATURES(= features' not described in 'virtio_device' Signed-off-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 1df869061bf3..917e4528bfbf 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -150,6 +150,7 @@ struct_xforms =3D [ struct_args_pattern + r'\)', re.S), r'\1 \2[]'), (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', r= e.S), r'dma_addr_t \1'), (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re= .S), r'__u32 \1'), + (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1; u64= \1_array[VIRTIO_FEATURES_U64S]; }'), ] # # Regexes here are guaranteed to have the end delimiter matching --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id E5E35425CE4; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469671; cv=none; b=M5L8XCY0zzKi2IkHc+V4K9VouMHioPbAW8SgpV8ImxgloPcH2HGA7sLHwhhlAzzbl5DY6urNteOSmZDITmgjyFdejLeoeNp2denZQATQCRArXgY/u78AKh50Orjo3+8hq/8xTaIz29Jv+AgOV8irDAm5xFYV4YGbXB3+wL8JiIQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469671; c=relaxed/simple; bh=krVuokXcDhCbYSFJJTspYEwemL25zHoulATY+A6cBdM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=u26DXnGNdIsHvimCLlS7DixQ6HGmHSoTtjSh3HT801uPeS1GhdV/hPoLxtRrwiJ7HgDgrRuFm9/aPbC185uQPwVRF9tympG+STBU3qT0ONdp5BjMoVot3C6yykFGTJJD1ZadLVDmKGn10gknzBFD06mKhjWKmIgvcicElBp5FlA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Q8NPyhwt; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="Q8NPyhwt" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C417DC2BCB2; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469670; bh=krVuokXcDhCbYSFJJTspYEwemL25zHoulATY+A6cBdM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Q8NPyhwtgCAgKtm9B1ikATdhImsF4zpAgZVPcFtuKFDQ1nZqrTGrphRBmY0ZnyPrR fLX7iqDmS+XlIBpW6OW1ce2R/biSY1RukB5kpn5rVR52K1z+k2Som5ytkH+HsJtKz3 5mLgb7Ft3XnFZGMFT8FdZMu49C/b4GReujtiszsOYwp49PqtCQrxydVtsQSEOrmhSs FIOL5HKjnqrDX02r1ne/mym6vakGCy0eO5usQ1bDJyGCIvYY1IgdTboyat0CfLATQ9 p54CCaLf+QRrKWkT3fi5rbhPRLx0AHpsMFxaQDseevn1oL5PMTwmZBNXtIpIE9iQW5 nOSbt7p/8wNpg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KS-0000000039Z-3OS1; Mon, 02 Mar 2026 17:41:08 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 11/18] docs: kdoc_re: better show KernRe() at documentation Date: Mon, 2 Mar 2026 17:40:54 +0100 Message-ID: <80d27732368c14125c1b76048a70d8b4aee527ef.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab the __repr__() function is used by autodoc to document macro initialization. Add a better representation for them. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 6c44fcce0415..664c04c8cc9f 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -52,7 +52,28 @@ class KernRe: return self.regex.pattern =20 def __repr__(self): - return f're.compile("{self.regex.pattern}")' + """ + Returns a displayable version of the class init. + """ + + flag_map =3D { + re.IGNORECASE: "re.I", + re.MULTILINE: "re.M", + re.DOTALL: "re.S", + re.VERBOSE: "re.X", + } + + flags =3D [] + for flag, name in flag_map.items(): + if self.regex.flags & flag: + flags.append(name) + + flags_name =3D " | ".join(flags) + + if flags_name: + return f'KernRe("{self.regex.pattern}", {flags_name})' + else: + return f'KernRe("{self.regex.pattern}")' =20 def __add__(self, other): """ --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 4486842669A; Mon, 2 Mar 2026 16:41:11 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469671; cv=none; b=sZaJASJwTRwGEp3wxmKEycbCUWDB5hoeREIvTBV/YQRNPPnIVYiv/QIYTB50zl1g712WcC318SPMZS7Ay5FCdUN72XX3uU9kVXq3FfrS3CEKMrdmMjojgsSpFVPZACUffJ3XnL/Ux4q+ltM5H9CcxHK66h0sq1N6vXqGqAOEq64= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469671; c=relaxed/simple; bh=Pg1w6h3oi09pGfE7ZeyRQdHpAcI21wEKTI+1Owlib1s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=NQ86hu7CXX78MPdblnuRPcSLM1OpPyQDNlma3v2NfVd6Nhgf65c5LdzgodCjaxUdX9l88TfUKZ8aYi40ys4qEg6KdD4bWHDCBFAJ50ME80eEH8DxxsePtiAEzUx9V/EG9FBH/8Dg42TNnEnPgrl6U/HOUWPQI3mx1Ian/pT5eo0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=gJzH6I4K; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="gJzH6I4K" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C07BCC19423; Mon, 2 Mar 2026 16:41:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469671; bh=Pg1w6h3oi09pGfE7ZeyRQdHpAcI21wEKTI+1Owlib1s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gJzH6I4K60Z7qHWMaoM3bGBRHPE+Ue73dpmFCrOCx0mNr8ohxsUQNrA2+siBkNKNN NXwEzarqiFpS89GTGh6eQKO/pzp+pprnuWJBwnEe7ZIHrV12BQd66zSUWktBKO8hTX yDJqUnKIhBeC1RaYFEHoou+rpAxCub4QiJCP3EkUx9JXQLIAUM8KDxH+0tSwSI6XcT g1EdmYdGaQh/ja3+O2+gNx9MV+eozNjII10t4sZJd8EogcTkse3x1NiOLKsbWo5EJn FSpRoBd3uZp90ZHekkOdsquzDlVuzd6MFAoXDKOhWsQuFsJAfN6A1RXgsGcrWw9kIB GsKhS6qnfbDnA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KT-000000003Am-00Xd; Mon, 02 Mar 2026 17:41:09 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, "Gustavo A. R. Silva" , Aleksandr Loktionov , Kees Cook , Randy Dunlap , Shuah Khan Subject: [PATCH 12/18] docs: kdoc_parser: move transform lists to a separate file Date: Mon, 2 Mar 2026 17:40:55 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Over the time, most of the changes at kernel-doc are related to maintaining a list of transforms to convert macros into pure C code. Place such transforms on a separate module, to cleanup the parser module. There is an advantage on that: QEMU also uses our own kernel-doc, but the xforms list there is different. By placing it on a separate module, we can minimize the differences and make it easier to keep QEMU in sync with Kernel upstream. No functional changes. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- Documentation/tools/kdoc_parser.rst | 8 ++ tools/lib/python/kdoc/kdoc_files.py | 3 +- tools/lib/python/kdoc/kdoc_parser.py | 145 +----------------------- tools/lib/python/kdoc/xforms_lists.py | 153 ++++++++++++++++++++++++++ 4 files changed, 168 insertions(+), 141 deletions(-) create mode 100644 tools/lib/python/kdoc/xforms_lists.py diff --git a/Documentation/tools/kdoc_parser.rst b/Documentation/tools/kdoc= _parser.rst index 03ee54a1b1cc..55b202173195 100644 --- a/Documentation/tools/kdoc_parser.rst +++ b/Documentation/tools/kdoc_parser.rst @@ -4,6 +4,14 @@ Kernel-doc parser stage =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 +C replacement rules used by the parser +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. automodule:: lib.python.kdoc.xforms_lists + :members: + :show-inheritance: + :undoc-members: + File handler classes =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kd= oc_files.py index 022487ea2cc6..33618c6abec2 100644 --- a/tools/lib/python/kdoc/kdoc_files.py +++ b/tools/lib/python/kdoc/kdoc_files.py @@ -15,6 +15,7 @@ import os import re =20 from kdoc.kdoc_parser import KernelDoc +from kdoc.xforms_lists import CTransforms from kdoc.kdoc_output import OutputFormat =20 =20 @@ -117,7 +118,7 @@ class KernelFiles(): if fname in self.files: return =20 - doc =3D KernelDoc(self.config, fname) + doc =3D KernelDoc(self.config, fname, CTransforms()) export_table, entries =3D doc.parse_kdoc() =20 self.export_table[fname] =3D export_table diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 917e4528bfbf..d7daf658e9d2 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -69,89 +69,6 @@ doc_begin_func =3D KernRe(str(doc_com) + # initial " *= ' r'(?:[-:].*)?$', # description (not captured) cache =3D False) =20 -# -# Here begins a long set of transformations to turn structure member prefi= xes -# and macro invocations into something we can parse and generate kdoc for. -# -struct_args_pattern =3D r'([^,)]+)' - -struct_xforms =3D [ - # Strip attributes - (KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", flags=3Dre.I |= re.S, cache=3DFalse), ' '), - (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), - (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), - (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), - (KernRe(r'\s*__packed\s*', re.S), ' '), - (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), - (KernRe(r'\s*__private', re.S), ' '), - (KernRe(r'\s*__rcu', re.S), ' '), - (KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '), - (KernRe(r'\s*____cacheline_aligned', re.S), ' '), - (KernRe(r'\s*__cacheline_group_(begin|end)\([^\)]+\);'), ''), - # - # Unwrap struct_group macros based on this definition: - # __struct_group(TAG, NAME, ATTRS, MEMBERS...) - # which has variants like: struct_group(NAME, MEMBERS...) - # Only MEMBERS arguments require documentation. - # - # Parsing them happens on two steps: - # - # 1. drop struct group arguments that aren't at MEMBERS, - # storing them as STRUCT_GROUP(MEMBERS) - # - # 2. remove STRUCT_GROUP() ancillary macro. - # - # The original logic used to remove STRUCT_GROUP() using an - # advanced regex: - # - # \bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*; - # - # with two patterns that are incompatible with - # Python re module, as it has: - # - # - a recursive pattern: (?1) - # - an atomic grouping: (?>...) - # - # I tried a simpler version: but it didn't work either: - # \bSTRUCT_GROUP\(([^\)]+)\)[^;]*; - # - # As it doesn't properly match the end parenthesis on some cases. - # - # So, a better solution was crafted: there's now a NestedMatch - # class that ensures that delimiters after a search are properly - # matched. So, the implementation to drop STRUCT_GROUP() will be - # handled in separate. - # - (KernRe(r'\bstruct_group\s*\(([^,]*,)', re.S), r'STRUCT_GROUP('), - (KernRe(r'\bstruct_group_attr\s*\(([^,]*,){2}', re.S), r'STRUCT_GROUP(= '), - (KernRe(r'\bstruct_group_tagged\s*\(([^,]*),([^,]*),', re.S), r'struct= \1 \2; STRUCT_GROUP('), - (KernRe(r'\b__struct_group\s*\(([^,]*,){3}', re.S), r'STRUCT_GROUP('), - # - # Replace macros - # - # TODO: use NestedMatch for FOO($1, $2, ...) matches - # - # it is better to also move those to the NestedMatch logic, - # to ensure that parentheses will be properly matched. - # - (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re.S), - r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), - (KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)', re.S), - r'DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'), - (KernRe(r'DECLARE_BITMAP\s*\(' + struct_args_pattern + r',\s*' + struc= t_args_pattern + r'\)', - re.S), r'unsigned long \1[BITS_TO_LONGS(\2)]'), - (KernRe(r'DECLARE_HASHTABLE\s*\(' + struct_args_pattern + r',\s*' + st= ruct_args_pattern + r'\)', - re.S), r'unsigned long \1[1 << ((\2) - 1)]'), - (KernRe(r'DECLARE_KFIFO\s*\(' + struct_args_pattern + r',\s*' + struct= _args_pattern + - r',\s*' + struct_args_pattern + r'\)', re.S), r'\2 *\1'), - (KernRe(r'DECLARE_KFIFO_PTR\s*\(' + struct_args_pattern + r',\s*' + - struct_args_pattern + r'\)', re.S), r'\2 *\1'), - (KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\s*\(' + struct_args_pattern + r',\= s*' + - struct_args_pattern + r'\)', re.S), r'\1 \2[]'), - (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', r= e.S), r'dma_addr_t \1'), - (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re= .S), r'__u32 \1'), - (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1; u64= \1_array[VIRTIO_FEATURES_U64S]; }'), -] # # Regexes here are guaranteed to have the end delimiter matching # the start delimiter. Yet, right now, only one replace group @@ -161,62 +78,10 @@ struct_nested_prefixes =3D [ (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), ] =20 -# -# Transforms for function prototypes -# -function_xforms =3D [ - (KernRe(r"^static +"), ""), - (KernRe(r"^extern +"), ""), - (KernRe(r"^asmlinkage +"), ""), - (KernRe(r"^inline +"), ""), - (KernRe(r"^__inline__ +"), ""), - (KernRe(r"^__inline +"), ""), - (KernRe(r"^__always_inline +"), ""), - (KernRe(r"^noinline +"), ""), - (KernRe(r"^__FORTIFY_INLINE +"), ""), - (KernRe(r"__init +"), ""), - (KernRe(r"__init_or_module +"), ""), - (KernRe(r"__exit +"), ""), - (KernRe(r"__deprecated +"), ""), - (KernRe(r"__flatten +"), ""), - (KernRe(r"__meminit +"), ""), - (KernRe(r"__must_check +"), ""), - (KernRe(r"__weak +"), ""), - (KernRe(r"__sched +"), ""), - (KernRe(r"_noprof"), ""), - (KernRe(r"__always_unused *"), ""), - (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""), - (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""), - (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), - (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2= "), - (KernRe(r"__attribute_const__ +"), ""), - (KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+")= , ""), -] - -# -# Transforms for variable prototypes -# -var_xforms =3D [ - (KernRe(r"__read_mostly"), ""), - (KernRe(r"__ro_after_init"), ""), - (KernRe(r"LIST_HEAD\(([\w_]+)\)"), r"struct list_head \1"), - (KernRe(r"(?://.*)$"), ""), - (KernRe(r"(?:/\*.*\*/)"), ""), - (KernRe(r";$"), ""), -] - # # Ancillary functions # =20 -def apply_transforms(xforms, text): - """ - Apply a set of transforms to a block of text. - """ - for search, subst in xforms: - text =3D search.sub(subst, text) - return text - multi_space =3D KernRe(r'\s\s+') def trim_whitespace(s): """ @@ -395,11 +260,12 @@ class KernelDoc: #: String to write when a parameter is not described. undescribed =3D "-- undescribed --" =20 - def __init__(self, config, fname): + def __init__(self, config, fname, xforms): """Initialize internal variables""" =20 self.fname =3D fname self.config =3D config + self.xforms =3D xforms =20 # Initial state for the state machines self.state =3D state.NORMAL @@ -883,7 +749,7 @@ class KernelDoc: # Go through the list of members applying all of our transformatio= ns. # members =3D trim_private_members(members) - members =3D apply_transforms(struct_xforms, members) + members =3D self.xforms.apply("struct", members) =20 nested =3D NestedMatch() for search, sub in struct_nested_prefixes: @@ -1009,8 +875,7 @@ class KernelDoc: # Drop comments and macros to have a pure C prototype # if not declaration_name: - for r, sub in var_xforms: - proto =3D r.sub(sub, proto) + proto =3D self.xforms.apply("var", proto) =20 proto =3D proto.rstrip() =20 @@ -1091,7 +956,7 @@ class KernelDoc: # # Apply the initial transformations. # - prototype =3D apply_transforms(function_xforms, prototype) + prototype =3D self.xforms.apply("func", prototype) =20 # Yes, this truly is vile. We are looking for: # 1. Return type (may be nothing if we're looking at a macro) diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/= xforms_lists.py new file mode 100644 index 000000000000..e6e0302e5dd0 --- /dev/null +++ b/tools/lib/python/kdoc/xforms_lists.py @@ -0,0 +1,153 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright(c) 2026: Mauro Carvalho Chehab . + +import re + +from kdoc.kdoc_re import KernRe + +struct_args_pattern =3D r'([^,)]+)' + +class CTransforms: + """ + Data class containing a long set of transformations to turn + structure member prefixes, and macro invocations and variables + into something we can parse and generate kdoc for. + """ + + #: Transforms for structs and unions. + struct_xforms =3D [ + # Strip attributes + (KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", flags=3Dre= .I | re.S, cache=3DFalse), ' '), + (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__packed\s*', re.S), ' '), + (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), + (KernRe(r'\s*__private', re.S), ' '), + (KernRe(r'\s*__rcu', re.S), ' '), + (KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '), + (KernRe(r'\s*____cacheline_aligned', re.S), ' '), + (KernRe(r'\s*__cacheline_group_(begin|end)\([^\)]+\);'), ''), + # + # Unwrap struct_group macros based on this definition: + # __struct_group(TAG, NAME, ATTRS, MEMBERS...) + # which has variants like: struct_group(NAME, MEMBERS...) + # Only MEMBERS arguments require documentation. + # + # Parsing them happens on two steps: + # + # 1. drop struct group arguments that aren't at MEMBERS, + # storing them as STRUCT_GROUP(MEMBERS) + # + # 2. remove STRUCT_GROUP() ancillary macro. + # + # The original logic used to remove STRUCT_GROUP() using an + # advanced regex: + # + # \bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*; + # + # with two patterns that are incompatible with + # Python re module, as it has: + # + # - a recursive pattern: (?1) + # - an atomic grouping: (?>...) + # + # I tried a simpler version: but it didn't work either: + # \bSTRUCT_GROUP\(([^\)]+)\)[^;]*; + # + # As it doesn't properly match the end parenthesis on some cases. + # + # So, a better solution was crafted: there's now a NestedMatch + # class that ensures that delimiters after a search are properly + # matched. So, the implementation to drop STRUCT_GROUP() will be + # handled in separate. + # + (KernRe(r'\bstruct_group\s*\(([^,]*,)', re.S), r'STRUCT_GROUP('), + (KernRe(r'\bstruct_group_attr\s*\(([^,]*,){2}', re.S), r'STRUCT_GR= OUP('), + (KernRe(r'\bstruct_group_tagged\s*\(([^,]*),([^,]*),', re.S), r'st= ruct \1 \2; STRUCT_GROUP('), + (KernRe(r'\b__struct_group\s*\(([^,]*,){3}', re.S), r'STRUCT_GROUP= ('), + # + # Replace macros + # + # TODO: use NestedMatch for FOO($1, $2, ...) matches + # + # it is better to also move those to the NestedMatch logic, + # to ensure that parentheses will be properly matched. + # + (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re.S), + r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), + (KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)', re.S), + r'DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'), + (KernRe(r'DECLARE_BITMAP\s*\(' + struct_args_pattern + r',\s*' + s= truct_args_pattern + r'\)', + re.S), r'unsigned long \1[BITS_TO_LONGS(\2)]'), + (KernRe(r'DECLARE_HASHTABLE\s*\(' + struct_args_pattern + r',\s*' = + struct_args_pattern + r'\)', + re.S), r'unsigned long \1[1 << ((\2) - 1)]'), + (KernRe(r'DECLARE_KFIFO\s*\(' + struct_args_pattern + r',\s*' + st= ruct_args_pattern + + r',\s*' + struct_args_pattern + r'\)', re.S), r'\2 *\1'), + (KernRe(r'DECLARE_KFIFO_PTR\s*\(' + struct_args_pattern + r',\s*' + + struct_args_pattern + r'\)', re.S), r'\2 *\1'), + (KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\s*\(' + struct_args_pattern + = r',\s*' + + struct_args_pattern + r'\)', re.S), r'\1 \2[]'), + (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)= ', re.S), r'dma_addr_t \1'), + (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)'= , re.S), r'__u32 \1'), + (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1;= u64 \1_array[VIRTIO_FEATURES_U64S]; }'), + ] + + #: Transforms for function prototypes. + function_xforms =3D [ + (KernRe(r"^static +"), ""), + (KernRe(r"^extern +"), ""), + (KernRe(r"^asmlinkage +"), ""), + (KernRe(r"^inline +"), ""), + (KernRe(r"^__inline__ +"), ""), + (KernRe(r"^__inline +"), ""), + (KernRe(r"^__always_inline +"), ""), + (KernRe(r"^noinline +"), ""), + (KernRe(r"^__FORTIFY_INLINE +"), ""), + (KernRe(r"__init +"), ""), + (KernRe(r"__init_or_module +"), ""), + (KernRe(r"__exit +"), ""), + (KernRe(r"__deprecated +"), ""), + (KernRe(r"__flatten +"), ""), + (KernRe(r"__meminit +"), ""), + (KernRe(r"__must_check +"), ""), + (KernRe(r"__weak +"), ""), + (KernRe(r"__sched +"), ""), + (KernRe(r"_noprof"), ""), + (KernRe(r"__always_unused *"), ""), + (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""), + (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), = ""), + (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), + (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1= , \2"), + (KernRe(r"__attribute_const__ +"), ""), + (KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\= s+"), ""), + ] + + #: Transforms for variable prototypes. + var_xforms =3D [ + (KernRe(r"__read_mostly"), ""), + (KernRe(r"__ro_after_init"), ""), + (KernRe(r"LIST_HEAD\(([\w_]+)\)"), r"struct list_head \1"), + (KernRe(r"(?://.*)$"), ""), + (KernRe(r"(?:/\*.*\*/)"), ""), + (KernRe(r";$"), ""), + ] + + #: Transforms main dictionary used at apply_transforms(). + xforms =3D { + "struct": struct_xforms, + "func": function_xforms, + "var": var_xforms, + } + + def apply(self, xforms_type, text): + """ + Apply a set of transforms to a block of text. + """ + if xforms_type not in self.xforms: + return text + + for search, subst in self.xforms[xforms_type]: + text =3D search.sub(subst, text) + return text --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 448FB42669B; Mon, 2 Mar 2026 16:41:11 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469671; cv=none; b=MSEdSTomSyOU+zUnyTK+Y6zgt1/IHz5iCUl5AZrigQvv8BtlA2gy23Q4g7tiDU6QG9GgyAmEY08MyfW5R5uSTiu36aotl75pSXjsYuBOFMBUb4UXTlHBhPLK20vSHnKWFBfV+AzQYgT8ZzbY1cnKU16qohldox9xeM5cv6/v8mg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469671; c=relaxed/simple; bh=tIjupFasOCXFkiwCnFBXnKQjfhLIL14356wka0J5sM8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=s6UZ13PFv8bNSRzQgWmUZ3rK2L5hSfV8TXrxDlGq8ZCT2YBLbx8tLIA3rbTVKbu2Qb3i0EIu+lmiETAN4ON0PYfuNWvES+aBmZ4JeW11fY73HDRF3GC57XXT3Z53i1VPHtIP0xYkoQX2nxqV2gjoIHHTfTv8FibWOnia6sb6i8Y= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=avyhZL2M; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="avyhZL2M" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 0FB05C2BC87; Mon, 2 Mar 2026 16:41:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469671; bh=tIjupFasOCXFkiwCnFBXnKQjfhLIL14356wka0J5sM8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=avyhZL2M6cSOjYWN53N6mBqvDdLitmhqjYn4nG85pJY7VmYFS5rWRAHtDgW12MhiH 20fM7HSN10dc7pXotk87hmMC6QLLLK3Y2Gxty4apA+wzMuajAxi3RgcEffZdydTV/P YGvMyGklwzHptJhS0G4JS9HmMQUW8Ihun7p8DTjO8CEKr5TY5pFC4MGdAysP5hEXAY 7yMJTmsHu74HkWtLuju4Yel1LiEdryoJ8kl2rLgdWaayok7KqRP3nJojOwWsghOe6+ 72ZcMxbcdgm4SioYbMbRvSshhjWh8MqBr1wRl6EncrOE8YoJo0TEmNxRDQ7UUr74YY ow2XUaWJE10CA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KT-000000003C0-0oZ7; Mon, 02 Mar 2026 17:41:09 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap , Stephen Rothwell Subject: [PATCH 13/18] docs: xforms_lists: ignore context analysis and lock attributes Date: Mon, 2 Mar 2026 17:40:56 +0100 Message-ID: <3c7fdfc364a8920f92530b47bdbf4bb29a40371f.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab From: Randy Dunlap Drop context analysis and lock (tracking) attributes to avoid kernel-doc warnings. There are now lots of warnings like these: Documentation/core-api/kref:328: ../include/linux/kref.h:72: WARNING: I= nvalid C declaration: Expected end of definition. [error at 96] int kref_put_mutex (struct kref *kref, void (*release)(struct kref *k= ref), struct mutex *mutex) __cond_acquires(true# mutex) ---------------------------------------------------------------------= ---------------------------^ Documentation/core-api/kref:328: ../include/linux/kref.h:94: WARNING: I= nvalid C declaration: Expected end of definition. [error at 92] int kref_put_lock (struct kref *kref, void (*release)(struct kref *kr= ef), spinlock_t *lock) __cond_acquires(true# lock) ---------------------------------------------------------------------= -----------------------^ The regex is suggested by Mauro; mine was too greedy. Thanks. Updated context analysis and lock macros list provided by PeterZ. Thanks. [mchehab: modified to be applied after xforms_lists split] Reported-by: Stephen Rothwell Closes: https://lore.kernel.org/all/20260107161548.45530e1c@canb.auug.org.a= u/ Signed-off-by: Randy Dunlap Reviewed-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_parser.py | 10 ++++++++++ tools/lib/python/kdoc/xforms_lists.py | 5 +++++ 2 files changed, 15 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index d7daf658e9d2..503a18212747 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -75,6 +75,16 @@ doc_begin_func =3D KernRe(str(doc_com) + # initial " *= ' # is allowed. # struct_nested_prefixes =3D [ + (re.compile(r"__cond_acquires\s*\("), ""), + (re.compile(r"__cond_releases\s*\("), ""), + (re.compile(r"__acquires\s*\("), ""), + (re.compile(r"__releases\s*\("), ""), + (re.compile(r"__must_hold\s*\("), ""), + (re.compile(r"__must_not_hold\s*\("), ""), + (re.compile(r"__must_hold_shared\s*\("), ""), + (re.compile(r"__cond_acquires_shared\s*\("), ""), + (re.compile(r"__acquires_shared\s*\("), ""), + (re.compile(r"__releases_shared\s*\("), ""), (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), ] =20 diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/= xforms_lists.py index e6e0302e5dd0..1bda7c4634c3 100644 --- a/tools/lib/python/kdoc/xforms_lists.py +++ b/tools/lib/python/kdoc/xforms_lists.py @@ -22,6 +22,8 @@ class CTransforms: (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ' '), + (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ' '), (KernRe(r'\s*__packed\s*', re.S), ' '), (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), (KernRe(r'\s*__private', re.S), ' '), @@ -120,6 +122,7 @@ class CTransforms: (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), = ""), (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1= , \2"), + (KernRe(r"__no_context_analysis\s*"), ""), (KernRe(r"__attribute_const__ +"), ""), (KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\= s+"), ""), ] @@ -128,6 +131,8 @@ class CTransforms: var_xforms =3D [ (KernRe(r"__read_mostly"), ""), (KernRe(r"__ro_after_init"), ""), + (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ""), + (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ""), (KernRe(r"LIST_HEAD\(([\w_]+)\)"), r"struct list_head \1"), (KernRe(r"(?://.*)$"), ""), (KernRe(r"(?:/\*.*\*/)"), ""), --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 9AF7A426D1E; Mon, 2 Mar 2026 16:41:11 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469671; cv=none; b=WieWPNz64ZRHPwIAyK604FkjHaCFWhluxlRvJHbmYFoqvw4FuuaxLCrhIKOpDwnSa9KnNKnWyRNRkPy/2ygTiLibCMMpTD92IPZjY+OOvsF9k2pgrty6XgF2qANr3bu9wm7OEDj5oFOfyGFEaAT9475/5/lGCebmbdhsJdZRbt4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469671; c=relaxed/simple; bh=TauImqU7dyAB+n4W/42lNCpNZkqn+rlErO2lHzaJpt4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ZV2x+6YDwUuWQK50RfHfK52Ydh6V6J29oWEiFm+AOjSvHAVTTpLYnp34ZUyPzhyfP9A5yGFP20v2zscBqzANhdKH3Gpg++vxMayHqQfeoDX9VJTMKp6pPhMW4bxMqi3eO2lg8DX208mjxt+uDFJYHt4DlS65/BVlAzanBl3tMeA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=PqPKaFZk; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="PqPKaFZk" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6DDF8C2BCB2; Mon, 2 Mar 2026 16:41:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469671; bh=TauImqU7dyAB+n4W/42lNCpNZkqn+rlErO2lHzaJpt4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PqPKaFZkvBv5yyfQA8IEd34tg3mXHSq41TaivZWBpA71dsv4etobTZR1ishTroAb3 +OV+ipl1j3cgKQ/WbvI5GgWTkiYY5wT6MNy3JZwALai3/JlnxEH/ch0r9yFqIo4Izk cuSPlIC1h3iZTHHyPKBvJTbAKjtauAi9ML/2NrKGDIWgI2nH1QJtf/k3i1WdcNdjBZ XJCNP1d118CUtL4EEasM4U9HJzOwDeRBo1y97Qr9Vg/dhI+wCm5p7gLJ2JP9FsfrmV uQvMLV6MNIgIIveyhobviF+Q+uvEzsaMJqrMtPHiJ1OS6O786l1YD7ngC4/4MhzOGX mfHFPtBHqkmWQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KT-000000003DD-1dMp; Mon, 02 Mar 2026 17:41:09 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 14/18] docs: kdoc_re: handle strings and escape chars on NextMatch Date: Mon, 2 Mar 2026 17:40:57 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The logic inside NestedMatch currently doesn't consider that function arguments may have chars and strings, which may eventually contain delimiters. Add logic to handle strings and escape characters on them. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 664c04c8cc9f..0a7f12616f9f 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -216,6 +216,8 @@ class NestedMatch: for match_re in regex.finditer(line): start =3D match_re.start() offset =3D match_re.end() + string_char =3D None + escape =3D False =20 d =3D line[offset - 1] if d not in self.DELIMITER_PAIRS: @@ -229,6 +231,22 @@ class NestedMatch: =20 d =3D line[pos] =20 + if escape: + escape =3D False + continue + + if string_char: + if d =3D=3D '\\': + escape =3D True + elif d =3D=3D string_char: + string_char =3D None + + continue + + if d in ('"', "'"): + string_char =3D d + continue + if d in self.DELIMITER_PAIRS: end =3D self.DELIMITER_PAIRS[d] =20 --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 8C761426D15; Mon, 2 Mar 2026 16:41:11 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469671; cv=none; b=WhkZOOCBMldCx3iL+0V7N+H3pocg/HobOjlzVi1XZLE0IFL10wbZUvk87+/HTUBvf8wz7Z6zFkZ9mLnTTmFi+Rb4xZauEQCOr6/7ZgJzOLf6SEQ9MxY80nSwOZbMwZ+Afo068J1R10lqK71e9XaapkXfJ8Bey+kartPg2mPK26s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469671; c=relaxed/simple; bh=G52yNr/mjvH//WKN8I/I22tm0myDjYubrgazvSxDbzk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=DPzGaA+74CG4Hw5vlF5RDoBVVgVq8z9e/b2Yaj9Py3/U/X/r3um9D5wfhQG8J9iMpWQEgGAltTl5AQ15qBHQdVzI2DfmlsKWl7zAVwCEIBkcvHt6ujhYeKxJuviKeUDYDBCVSnursZiWOUAvmifeMM+5jb2y06RwEGFgNkcRXks= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Paeiv/e4; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="Paeiv/e4" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6DD20C2BC87; Mon, 2 Mar 2026 16:41:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469671; bh=G52yNr/mjvH//WKN8I/I22tm0myDjYubrgazvSxDbzk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Paeiv/e4uMb5jfkxD9Ej7ISMmm2u6rvgsxtr36hWtUYono287sIVUitmcYttya+ta CI1Pubsa244rO4mqN8N47vp1cTyYdnxmlvDXea1oamStj3B9EjB2mOR6yFAPm/7QI3 f59K2uyVp6djDUAosimso3VJck04KgZVQaRq3vqrmHEyVbflsCI0Y9HIkxtC4JfJL5 qWSr3PddOFmZ8AYyO+pZiXAGMyCh6sIILIH8d/DUjAaBm+F4wBqIKQX0VAkmCATuZD dCaTYQDc+DphChemHUakuOLSxzS1WDLlgExiSiMymfxYh5FFrFULy752Yu2J2rJDf7 ZYl/skuh4AN0w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KT-000000003ES-2Qxk; Mon, 02 Mar 2026 17:41:09 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 15/18] docs: kdoc_re: don't recompile NestedMatch regex every time Date: Mon, 2 Mar 2026 17:40:58 +0100 Message-ID: <0cf2b72d4785aa8b727188b56688ff442d1c65ce.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Store delimiters and its regex-compiled version as const vars. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 35 ++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 0a7f12616f9f..00afa5bccd6d 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -99,6 +99,13 @@ class KernRe: self.last_match =3D self.regex.search(string) return self.last_match =20 + def finditer(self, string): + """ + Alias to re.finditer. + """ + + return self.regex.finditer(string) + def findall(self, string): """ Alias to re.findall. @@ -134,6 +141,16 @@ class KernRe: =20 return self.last_match.groups() =20 +#: Nested delimited pairs (brackets and parenthesis) +DELIMITER_PAIRS =3D { + '{': '}', + '(': ')', + '[': ']', +} + +#: compiled delimiters +RE_DELIM =3D KernRe(r'[\{\}\[\]\(\)]') + =20 class NestedMatch: """ @@ -183,14 +200,6 @@ class NestedMatch: # # FOO(arg1, arg2, arg3) =20 - DELIMITER_PAIRS =3D { - '{': '}', - '(': ')', - '[': ']', - } - - RE_DELIM =3D re.compile(r'[\{\}\[\]\(\)]') - def _search(self, regex, line): """ Finds paired blocks for a regex that ends with a delimiter. @@ -220,13 +229,13 @@ class NestedMatch: escape =3D False =20 d =3D line[offset - 1] - if d not in self.DELIMITER_PAIRS: + if d not in DELIMITER_PAIRS: continue =20 - end =3D self.DELIMITER_PAIRS[d] + end =3D DELIMITER_PAIRS[d] stack.append(end) =20 - for match in self.RE_DELIM.finditer(line[offset:]): + for match in RE_DELIM.finditer(line[offset:]): pos =3D match.start() + offset =20 d =3D line[pos] @@ -247,8 +256,8 @@ class NestedMatch: string_char =3D d continue =20 - if d in self.DELIMITER_PAIRS: - end =3D self.DELIMITER_PAIRS[d] + if d in DELIMITER_PAIRS: + end =3D DELIMITER_PAIRS[d] =20 stack.append(end) continue --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 256E2426ED8; Mon, 2 Mar 2026 16:41:12 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469672; cv=none; b=fjhIxCShxGSXYokAImQ0qPpZc8POrGpdaYhKicedafcZFQNbukFEHuwpzcU+4CbNJSPTrvUDjokfNC8+YysPpICSieyJUlGMoyqkSv6+zp6wo/7RQEBw+2nJA29djIlBVK6pt/D+TyddbQnngvkwJw1q3S5xE30c/Dc5D/8gfDY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469672; c=relaxed/simple; bh=5Li4bPNf54tBE9w7pNezt1RbIizsyzOaZvi5OGnyIRY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Fje1wRFS8bXx0wFl6CpV3S97ekHRMy9V1zqAx2KdpM+WAhTYvzRXwTV+I6Dw29qhU4/w73pRu6AzEPORDFc+71MmfgoyP+RJyUAU6pIjHJMxMd4TeLk9qIO9SojMeQk3Slpg0Y7+HE9U4taKGMldsu3XY3MlVMnO8k8KoUqMww4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=kDoqCOPE; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="kDoqCOPE" Received: by smtp.kernel.org (Postfix) with ESMTPSA id EE60DC2BCAF; Mon, 2 Mar 2026 16:41:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469672; bh=5Li4bPNf54tBE9w7pNezt1RbIizsyzOaZvi5OGnyIRY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=kDoqCOPEBP9CVRmG+uWmRhE2CnUEUUJGrD1kT7q0eOiEmgqr+iU4mRjNLpSdloSgi xDxprJ7zyGmLTTzaNSj0Od9exHRwwScrDsfZA7wQbIGsIqSRNmqbbv4y4K4NJN/BG1 R77pH90i7g0lYkO0jaFhEvG0hYXHZazIZn67f80o3vdYtLD8xNIAhtg2GO5Gl1idtY m/WYYMaEErOlfRIz8gnyAuEhKv6NEWXz/S2p7z9KAxiY6eMCKdGMmgYHbGU1yFJRse TgNZg2gDxV7r+FKONY+mhE5Ag8uqGyXzqkcIikuSBfztozpdRay3nk25fmICEtaEHV 8m+bSDr4Qi1PQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KT-000000003Fh-3EF9; Mon, 02 Mar 2026 17:41:09 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 16/18] docs: kdoc_re: Change NestedMath args replacement to \0 Date: Mon, 2 Mar 2026 17:40:59 +0100 Message-ID: <46e383118be9d9e432e3814fe819ebb12261d7b4.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Future patches will allow parsing each argument instead of the hole set. Prepare for it by changing the replace all args from \1 to \0. No functional changes. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 2 +- tools/lib/python/kdoc/kdoc_re.py | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 503a18212747..0f90c16cb51a 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -85,7 +85,7 @@ struct_nested_prefixes =3D [ (re.compile(r"__cond_acquires_shared\s*\("), ""), (re.compile(r"__acquires_shared\s*\("), ""), (re.compile(r"__releases_shared\s*\("), ""), - (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), + (re.compile(r'\bSTRUCT_GROUP\('), r'\0'), ] =20 # diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 00afa5bccd6d..ea4f6f3d9e42 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -188,7 +188,7 @@ class NestedMatch: # except that the content inside the match group is delimiter-aligned. # # The content inside parentheses is converted into a single replace - # group (e.g. r`\1'). + # group (e.g. r`\0'). # # It would be nice to change such definition to support multiple # match groups, allowing a regex equivalent to: @@ -291,7 +291,7 @@ class NestedMatch: =20 if the sub argument contains:: =20 - r'\1' + r'\0' =20 it will work just like re: it places there the matched paired data with the delimiter stripped. @@ -310,9 +310,9 @@ class NestedMatch: # Value, ignoring start/end delimiters value =3D line[end:pos - 1] =20 - # replaces \1 at the sub string, if \1 is used there + # replaces \0 at the sub string, if \0 is used there new_sub =3D sub - new_sub =3D new_sub.replace(r'\1', value) + new_sub =3D new_sub.replace(r'\0', value) =20 out +=3D new_sub =20 --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 1C567426ED2; Mon, 2 Mar 2026 16:41:12 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469672; cv=none; b=HwX/HvqiCJu7Fs1/Hu0mY2PHPN0oVwiFIRZbO5qLezk5ZX1UH+KcUq7P+0gQVmwDdM3crsWoWWb/3gUgG9rhBDEmvk38Iwb/N440iXi+WxYAwINoX+cI1aOIdUGDHfn1mf4yy1PcNUb3stz+MjNy4J3iV+ljhZwnk5EZu+vnhBU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469672; c=relaxed/simple; bh=FcrszWhBlb6nxazGa/lNPzUht2XLW2uAQU9wgUZIfpU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Qh4wLF4o71LWUvYjGYuLJwkO07a6nTAjD3MbOTpz0QN2Xeoh/RmLKA6KasDGbo2r64vuJCa2E7412UjRW4Qr3mKqm5OjNIxJcixi9kjVglwNJy8mz7ZHoHzn+V+b0AimL+8hffi9tA0IixYpZJd0r21Nrp4iD2P8y0yy5CECO0g= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=uMkZ7Vng; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="uMkZ7Vng" Received: by smtp.kernel.org (Postfix) with ESMTPSA id EF0CBC4AF09; Mon, 2 Mar 2026 16:41:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469672; bh=FcrszWhBlb6nxazGa/lNPzUht2XLW2uAQU9wgUZIfpU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uMkZ7VngWXZlXBVT1F0VOQ03Q9QVmHA2OTzH3t4BCeumNHZKTZPLgefAB0iQwDCK1 lRWpz66WxCZM9e1NW5J48zViiCcz3z+tD1K0WxqQPXxF7sDOdT8fsLOjd2GN45OzKx dbizHHB3m0SA53gv8GJ1LnrfQbQ2675vTtzISXsih7FwrTUFkqJLO+7PEhnV0eUZzX WK0coozlPM4QGySXThfzTTpVQ0vomcXu+H7D1WC/AcubS6yG6kZsKFbZOWgEWw0r59 REiNjm5+D7qgeRv5Eq8uoT1PqYfvtQHBNlIdjB/g1oxh0NdNX9TDRIAAierxKGrQ7j fXx5MzgmcrsXw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KT-000000003Gz-42ow; Mon, 02 Mar 2026 17:41:09 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 17/18] docs: kdoc_re: make NestedMatch use KernRe Date: Mon, 2 Mar 2026 17:41:00 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Instead of using re_compile, let's create the class with the regex and use KernRe to keep it cached. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 25 ++++++++++++------------- tools/lib/python/kdoc/kdoc_re.py | 24 +++++++++++++++++------- 2 files changed, 29 insertions(+), 20 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 0f90c16cb51a..cd9857906a2b 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -75,17 +75,17 @@ doc_begin_func =3D KernRe(str(doc_com) + # initial " = * ' # is allowed. # struct_nested_prefixes =3D [ - (re.compile(r"__cond_acquires\s*\("), ""), - (re.compile(r"__cond_releases\s*\("), ""), - (re.compile(r"__acquires\s*\("), ""), - (re.compile(r"__releases\s*\("), ""), - (re.compile(r"__must_hold\s*\("), ""), - (re.compile(r"__must_not_hold\s*\("), ""), - (re.compile(r"__must_hold_shared\s*\("), ""), - (re.compile(r"__cond_acquires_shared\s*\("), ""), - (re.compile(r"__acquires_shared\s*\("), ""), - (re.compile(r"__releases_shared\s*\("), ""), - (re.compile(r'\bSTRUCT_GROUP\('), r'\0'), + (NestedMatch(r"__cond_acquires\s*\("), ""), + (NestedMatch(r"__cond_releases\s*\("), ""), + (NestedMatch(r"__acquires\s*\("), ""), + (NestedMatch(r"__releases\s*\("), ""), + (NestedMatch(r"__must_hold\s*\("), ""), + (NestedMatch(r"__must_not_hold\s*\("), ""), + (NestedMatch(r"__must_hold_shared\s*\("), ""), + (NestedMatch(r"__cond_acquires_shared\s*\("), ""), + (NestedMatch(r"__acquires_shared\s*\("), ""), + (NestedMatch(r"__releases_shared\s*\("), ""), + (NestedMatch(r'\bSTRUCT_GROUP\('), r'\0'), ] =20 # @@ -761,9 +761,8 @@ class KernelDoc: members =3D trim_private_members(members) members =3D self.xforms.apply("struct", members) =20 - nested =3D NestedMatch() for search, sub in struct_nested_prefixes: - members =3D nested.sub(search, sub, members) + members =3D search.sub(search, sub, members) # # Deal with embedded struct and union members, and drop enums enti= rely. # diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index ea4f6f3d9e42..085b89a4547c 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -200,7 +200,10 @@ class NestedMatch: # # FOO(arg1, arg2, arg3) =20 - def _search(self, regex, line): + def __init__(self, regex): + self.regex =3D KernRe(regex) + + def _search(self, line): """ Finds paired blocks for a regex that ends with a delimiter. =20 @@ -222,7 +225,7 @@ class NestedMatch: =20 stack =3D [] =20 - for match_re in regex.finditer(line): + for match_re in self.regex.finditer(line): start =3D match_re.start() offset =3D match_re.end() string_char =3D None @@ -270,7 +273,7 @@ class NestedMatch: yield start, offset, pos + 1 break =20 - def search(self, regex, line): + def search(self, line): """ This is similar to re.search: =20 @@ -278,12 +281,12 @@ class NestedMatch: returning occurrences only if all delimiters are paired. """ =20 - for t in self._search(regex, line): + for t in self._search(line): =20 yield line[t[0]:t[2]] =20 - def sub(self, regex, sub, line, count=3D0): - r""" + def sub(self, sub, line, count=3D0): + """ This is similar to re.sub: =20 It matches a regex that it is followed by a delimiter, @@ -304,7 +307,7 @@ class NestedMatch: cur_pos =3D 0 n =3D 0 =20 - for start, end, pos in self._search(regex, line): + for start, end, pos in self._search(line): out +=3D line[cur_pos:start] =20 # Value, ignoring start/end delimiters @@ -331,3 +334,10 @@ class NestedMatch: out +=3D line[cur_pos:l] =20 return out + + def __repr__(self): + """ + Returns a displayable version of the class init. + """ + + return f'NestedMatch("{self.regex.regex.pattern}")' --=20 2.52.0 From nobody Thu Apr 9 13:31:31 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 25601426ED6; Mon, 2 Mar 2026 16:41:12 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469672; cv=none; b=dlc6tpXFX2xJ9rZYAnQcd63ejpmqLnUH1vw8MRhKDt0uMGHTL1A7iFMcP8QjkdpjTm514nD3EONLUMnoaoYIiP3Yr4FLVn0SscePvFn+xMytNzZ/SRK0MLiK7qOqrpHG7Bxs/zIrmBPn5ZdJXnzQPBFk9dTMMn0GGVuEKd7yfoA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772469672; c=relaxed/simple; bh=t77gn4U/VzR14zgC6Ju/IS9Cd/1izGmRsVc9qw15YwI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=XdgcKq/MsD0z5a8QCuTrKbOneakOmnoQ+dBI/0Xdm7/AgIAM88Cfr2OJcRjhsM5kpgQ4kwPoxeJSmoFthzbbja/8YecK6uE6hb3+8G6hzyzcqdlHwqh4PoLSSZuRKKgJcWT5jvHx1EJZuOOnr4SsBpictcIpI8tRp2EMRWbriXU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=gzlM5sWZ; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="gzlM5sWZ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id EE3E2C2BC87; Mon, 2 Mar 2026 16:41:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1772469672; bh=t77gn4U/VzR14zgC6Ju/IS9Cd/1izGmRsVc9qw15YwI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gzlM5sWZV80NN7sK3wasPoZV7Q7S94p209U9rY9jkpHVOK4c5xM686LEAJR7meKmD Fi3LURfZo88qfsxEJdWqEGsx85MsmFZUUPKF15ViQsHjB8NvU6yhCtzfJsfDJ96HfQ UX6xuLDlL4p7IEktboaE3685p2Dd5Uxdp0FD2CMF6tDO9lvOPPpj3fwgwkDqAOcL5P BTM8YlOVXkq/a/ZVxdzdsM2qlwKrfTJBRrvpxY724LCuqnaGUye8jxVqgTefX2ga2u LMVEEMdUZeSrgJWkokxJ1K3Fn6ESeg844Gr3F69eAqffm93IOMiVpWOjj9eO/5xj5r 0URb++8CTdqKA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vx6KU-000000003ID-0eLH; Mon, 02 Mar 2026 17:41:10 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 18/18] docs: kdoc_parser: move nested match transforms to xforms_lists.py Date: Mon, 2 Mar 2026 17:41:01 +0100 Message-ID: <762ce2a58ff024c1b0b6f6a6e05020d1415b8308.1772469446.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab As NestedMatch now has a sub method and a declaration close to what KernRe does, we can move the rules to xforms_lists and simplify kdoc_parser a little bit. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_parser.py | 21 --------------------- tools/lib/python/kdoc/xforms_lists.py | 14 +++++++++++++- 2 files changed, 13 insertions(+), 22 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index cd9857906a2b..edf70ba139a5 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -69,25 +69,6 @@ doc_begin_func =3D KernRe(str(doc_com) + # initial " *= ' r'(?:[-:].*)?$', # description (not captured) cache =3D False) =20 -# -# Regexes here are guaranteed to have the end delimiter matching -# the start delimiter. Yet, right now, only one replace group -# is allowed. -# -struct_nested_prefixes =3D [ - (NestedMatch(r"__cond_acquires\s*\("), ""), - (NestedMatch(r"__cond_releases\s*\("), ""), - (NestedMatch(r"__acquires\s*\("), ""), - (NestedMatch(r"__releases\s*\("), ""), - (NestedMatch(r"__must_hold\s*\("), ""), - (NestedMatch(r"__must_not_hold\s*\("), ""), - (NestedMatch(r"__must_hold_shared\s*\("), ""), - (NestedMatch(r"__cond_acquires_shared\s*\("), ""), - (NestedMatch(r"__acquires_shared\s*\("), ""), - (NestedMatch(r"__releases_shared\s*\("), ""), - (NestedMatch(r'\bSTRUCT_GROUP\('), r'\0'), -] - # # Ancillary functions # @@ -761,8 +742,6 @@ class KernelDoc: members =3D trim_private_members(members) members =3D self.xforms.apply("struct", members) =20 - for search, sub in struct_nested_prefixes: - members =3D search.sub(search, sub, members) # # Deal with embedded struct and union members, and drop enums enti= rely. # diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/= xforms_lists.py index 1bda7c4634c3..c07cbe1e6349 100644 --- a/tools/lib/python/kdoc/xforms_lists.py +++ b/tools/lib/python/kdoc/xforms_lists.py @@ -4,7 +4,7 @@ =20 import re =20 -from kdoc.kdoc_re import KernRe +from kdoc.kdoc_re import KernRe, NestedMatch =20 struct_args_pattern =3D r'([^,)]+)' =20 @@ -94,6 +94,18 @@ class CTransforms: (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)= ', re.S), r'dma_addr_t \1'), (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)'= , re.S), r'__u32 \1'), (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1;= u64 \1_array[VIRTIO_FEATURES_U64S]; }'), + + (NestedMatch(r"__cond_acquires\s*\("), ""), + (NestedMatch(r"__cond_releases\s*\("), ""), + (NestedMatch(r"__acquires\s*\("), ""), + (NestedMatch(r"__releases\s*\("), ""), + (NestedMatch(r"__must_hold\s*\("), ""), + (NestedMatch(r"__must_not_hold\s*\("), ""), + (NestedMatch(r"__must_hold_shared\s*\("), ""), + (NestedMatch(r"__cond_acquires_shared\s*\("), ""), + (NestedMatch(r"__acquires_shared\s*\("), ""), + (NestedMatch(r"__releases_shared\s*\("), ""), + (NestedMatch(r'\bSTRUCT_GROUP\('), r'\0'), ] =20 #: Transforms for function prototypes. --=20 2.52.0