From nobody Sat Feb 7 15:09:57 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 2545237BE6E; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=hlXhmLMEHFa7WfMsXIZa1yp/YRkGxeE1zXPaeqM975JOL6/ZfBhodraEp1j5/z3hDCtfyOOg669OMI/WjFMH8xXg/jKZNyG77XYqpVPZggB6MqPquq036my7/Fuz08yLV6oKRVAm81dAign2Z1vTZLlU78VMjcIaw+MuPh5k+ec= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=Mtp3U2b4BAZhIQ5Am742/0g+jFDD4JwsLEBjzPmmPH0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=gT/CNH5jhNnLrTf6PYDQA3rcmDGt/nwQ32Hwn+khr+PFO/5/Md2wxh+ZyB64p4Q4ZE2WIBtxukxw2V3NR9mfPWdbZJarD+h+gkypSHlh2Nwp7yMvqR5z973qhJfioxGOWRRVaBtQgNPVnKwqbpVaJxixusWmzEWWnlSGOG/GA0E= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=M6nosDk8; 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="M6nosDk8" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B54CBC2BCB0; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=Mtp3U2b4BAZhIQ5Am742/0g+jFDD4JwsLEBjzPmmPH0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=M6nosDk8fYDIsSlp6ATV417qFSFvZLeDrcJ0DFLzhIxpdgYZLsQidMIQGQwl45cOQ yfjBTYWAgl3mzRxHYG34D8EPENzj1qPGR0sCNr2yefv5CRmvtXxpiQZ7TivRqgM4Y5 +lw6ZFuHoPr1vtv8JL6yf3fwB+xmIz4ro22Y1lv8sB7PxDkFi+5B/6vQfy5RHBvdAT 4mwuWbPdeF1Ah5KSBYonlVIEUjl3Zj1Urv5wyjh5XNmq0EfxtDBsCOQZGnQg4VGGVP 6ILcnW9OT5nOXRqIY7VZvPRhbx5VgyhH/ptwuqGPPtZaOdzwv6IRTANelkqWi80P36 UjSi6lN6ygKSg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4m-0000000ERMb-2ntt; Thu, 29 Jan 2026 09:08:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 01/30] docs: kdoc_re: add support for groups() Date: Thu, 29 Jan 2026 09:07:52 +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 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 --- 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 2816bd9f90f8..19e777e2c97e 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 Sat Feb 7 15:09:57 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 1F45837B41F; Thu, 29 Jan 2026 08:08:30 +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=1769674111; cv=none; b=c0xGCYy5BTVDbL9DU3YWcognY9qdx6wJkwSNfPeRQAj0joBC5g+lQiT6cyhIMuRDj+Yci650hDURodqrdhRx1GHjDbnAY3ByM+iDTPCCj78Ol6KV7dPS2WzznckMB2Y55l3/EJF+s8uI9iDkHqnuS2UFh7jLe+Rik5cUPwpwgTQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=aGtXVSLt63dj+krdfmEJciMSaeT6Bvc5GNuMaIsTXoE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=dNH5mLjRNVkbgo5HWOrJOrthPmnHV1Kb3ZGbFYUjRLwGKYeVdzGIKFuagds+SnxXaAARC7mhkke7Hpb2fYyVBNsSzSj8wQeCCxDJZFqirKs7wOeIMitjhiAbZJ9RpYoFqDGt1i/lL3W6uXbDBFSdDahWwXEZNdxWHtSVxxymNys= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=GwUPwuKc; 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="GwUPwuKc" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A68E0C19421; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=aGtXVSLt63dj+krdfmEJciMSaeT6Bvc5GNuMaIsTXoE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GwUPwuKchix0ktaGFZ14BD7+iWe+YGEUESq5oT0WaHhHb6rszMj7fIaXDG9dn3yb8 DCU+GP/MdvDwctj36xsGMnzkJY6i73EcapVpFjojhXXx1BsgVLOklXUgfbFYsJoVXf iM3KDxbFQw0+ZQ29a/C4aD3ILPURhu8kDrhMyCQmoXktjOOEL6rqm5WFJ6sclD0QHe mmmogdnoD0jtWSKror7JoHDUsWqaY8eEsdmDYq+lOuonMxmWGKPcNjpDp8rYvlQXQn HVMKOrQ+fk5bKLKQ3RpqEcmCfp5buVAk0q+A20BIEwbWxIfpf3vgVaJmC0uE50nbor ad2VfdLhF2itg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4m-0000000ERMf-2vI7; Thu, 29 Jan 2026 09:08:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 02/30] docs: kdoc_re: don't go past the end of a line Date: Thu, 29 Jan 2026 09:07:53 +0100 Message-ID: <6c6504dbc4d78555392db94b93dab711eac83f41.1769673038.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 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 --- 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 19e777e2c97e..a0402c065d3a 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -265,7 +265,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 Sat Feb 7 15:09:57 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 1F4E937BE62; Thu, 29 Jan 2026 08:08:30 +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=1769674111; cv=none; b=aXUvHwQlsCF2Wo/ODUwxQYh/DbG3EXOF56/Hby9UkYMF2E5CwyxkAbcZdig3BswdG2VEv/Q84ztWSNukPvK0wTTH4P1EhDBVkyTDM7ZkZCRmFy//KexkI+mqrpphsW31yElI3HlWG/UiDYA52GpfUGjMzCI1pzPOwT2hBsiEGzM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=1OHigLaB0I9Gr4pd6M4Zc3FWOaEqquAXFRRO/Gxw3CM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=YdbIdywY2w4l8CH3i967pIL+pzl4g2NfuI30DzfciceVuwdFFYdOsBJgKBx/BX3qMySo4uuvm0QBSqO0kiz77Tvda/eB6Gt0JLJWprJC4HwlgpUjTZ7CEJhefEg00ptD0iFwlsrgFHWo2n16+UYCVpcm9rt+cSPaRjo8zeq98Kw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=D6iaNGnd; 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="D6iaNGnd" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A9F6EC116D0; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=1OHigLaB0I9Gr4pd6M4Zc3FWOaEqquAXFRRO/Gxw3CM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=D6iaNGndPXupEiDumBkRLVZUMruiYFF60cis6DEkfHTMrT1ojRfOsSFhzKX/Zl6oJ 1vihi+Xcwg3SCGXFyfkwhrQ52Yf25g53aaFKNYHcMfBSnpLiTS+bcBDtHDO2LX23bf uDPjD6KwQgxEOXOw4ndW8UXPQW0yCWa5gRJmQ6A+JBxx2G7/mWgUjRZU5R9SneThS4 jq9xDUSGEkqrOePWqAA9ZLLY159RU9DIUHFKbb2X+D0pNpnUoUkBINLeyKUlNHHAu3 iFUhgeNG05Bc1iolBe7MxaMA9uMffQBDtoB8vOoSMV/IidVdHazt8c8Wt6T9r39bP7 kCQKG2s61cLtg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4m-0000000ERMj-330l; Thu, 29 Jan 2026 09:08:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 03/30] docs: kdoc_parser: move var transformers to the beginning Date: Thu, 29 Jan 2026 09:07:54 +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 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 fd57944ae907..0b68b140cd02 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -191,6 +191,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 # @@ -971,15 +983,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 # @@ -1003,7 +1006,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 Sat Feb 7 15:09:57 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 2539C37BE6D; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=iU9E+wpAa2TM7f7uR8ViGpB1IeoOx8Ehj63KdthEIg8ppPGTPm5alnLXZigxzVU89HBEW2LdbIXv4YjGmEjoTAS5y2I4oRpN+U/akT336I/3LIMJyp2sp6cuH9VLLeekHLEWWtOuBzWPGxfP97YEcvhoTEHuAdgP4OXn3LpaSNU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=cuKy1d1D0xiQwJcdcAdfKB7F5IpylCi/Hc8WUScKfcE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=rz7E7w3I+xIcGCRrTLINDsSpOMuif/vpxtsdKj7YCVWRjTZseGGh54/QTmgMCbl3GKg/6PoKSaXUD8FBBkjSqdlyGCE4YXrkNnq8MHDd0n8xSsf+aAVnKwbay6kPc1MPqq4DRZIVoqPA5+s8RJ2K1RUV0FOr0qcZm4JbufV1LQI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=eUNW7Yi6; 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="eUNW7Yi6" Received: by smtp.kernel.org (Postfix) with ESMTPSA id ACC83C2BC86; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=cuKy1d1D0xiQwJcdcAdfKB7F5IpylCi/Hc8WUScKfcE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=eUNW7Yi6qDRcBxZQKGIHv++h7jftY5Lx/5e9cAaUluz/uZ8XGowG9rSE6Mepe+JDU erKZXjV6Tutztg/t4R5NmsUHiB6lJ299VMSnJyG6bbvCRPbU1dEp2GWiZj4n4O6Y7M /Zble7cP/kNtngyHwf4ElaBiFdmdGNmQuxuiNtx+dql6V8/rz8yvHjmDxhWyz3O9+d YtVzOetnKAyoaF9yDiesoRwnu1VthNIm1USEZ2KAEr7ZwP+yoZjKCIyQUxHP2ptd37 M85qR2ZpPvcsi8MQpuYc3eoV2ackZb4iycU2i4x4bL4/p/Is74sWcGoVOQmUOokcBf NUdW53gSasH3w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4m-0000000ERMn-3AIc; Thu, 29 Jan 2026 09:08:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 04/30] docs: kdoc_parser: don't mangle with function defines Date: Thu, 29 Jan 2026 09:07:55 +0100 Message-ID: <33b532261e00197d24d581be48db37a229b018fa.1769673038.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 0b68b140cd02..3ba2cda2487a 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 +"), ""), @@ -1065,10 +1065,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. # @@ -1087,6 +1084,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 Sat Feb 7 15:09:57 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 4C41137BE7E; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=GsgQb3R7k48il7sENLOTHlVyrBUXCitFzHfqKDW1QSlU1Soo5oriEN1yN81VWJltoC61XKtS1TZtYca5WC6Z78zZHGWaYAfeTt3jO21oCg998orGDyvd5CJYAimAXcbknHhXqp1adDGlbuwGNg6XWWekDqKSc5+a8v10uJE2qns= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=1UyEpa3PQCXAaiGwapZKBeWnBxx40S80+WhX3uQJt4s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=h9BtKGSNWo0vFZGszAHeslsVyvxYss9BvWEtwpqyV+F00ImjXz7Jqp4HWcyvGPqveVM9jdEgVLA9mLr0g+wBV7qgkrZeVgAv9MlPaeAV/RlogtlelYPUMSXoQ7OcOIeU3TN10z4QT+E7zccmJIMX76r3hyd6R+zXosRm2w6wikk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=EvhAAKzG; 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="EvhAAKzG" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BEABDC2BCB3; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=1UyEpa3PQCXAaiGwapZKBeWnBxx40S80+WhX3uQJt4s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=EvhAAKzGzTPtlEJDqqgaXGoU6hJ9BsLh3leiHmwqXSfooJg+7x1GRQDkkS7MC19mQ nh8Es9tT3u7tnQQsWSN4DSijg4RzHB5Z+b4dMn928lh8XMpsOBeG3LPVrV3Q/BiFpK 0Va0h5CtLNPuUvUh7pGMI/bM6sIOKg0sa8N6sUX3lSGbJvPTvrq+BoOJF9GsRcw/8G 6mGgJq0saXS4RlCPaeJpN5bahy3EOSz3yCRCtnYSkx5Ofe5/kSWSYDYHlOuH6FW2HC jl/Nq2CxVvodSVqr9bS+CKITvILAgyzV7EGpXvby4lonY9nXvSGB64+2fZHhXYPWcW fbo0gu191vE2Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4m-0000000ERMr-3HYB; Thu, 29 Jan 2026 09:08:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 05/30] docs: kdoc_parser: add functions support for NestedMatch Date: Thu, 29 Jan 2026 09:07:56 +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 Some annotations macros may have nested parenthesis, causing normal regex parsing to fail. Extend apply_transforms to also use NestedMatch and add support for nested 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 | 38 ++++++++++++++++++---------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 3ba2cda2487a..ae5b2ef80f75 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -152,7 +152,7 @@ struct_xforms =3D [ (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re= .S), r'__u32 \1'), ] # -# Regexes here are guaranteed to have the end delimiter matching +# Struct regexes here are guaranteed to have the end delimiter matching # the start delimiter. Yet, right now, only one replace group # is allowed. # @@ -160,6 +160,13 @@ struct_nested_prefixes =3D [ (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), ] =20 +# +# Function Regexes here are guaranteed to have the end delimiter matching +# the start delimiter. +# +function_nested_prefixes =3D [ +] + # # Transforms for function prototypes # @@ -207,13 +214,6 @@ var_xforms =3D [ # 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 =20 multi_space =3D KernRe(r'\s\s+') def trim_whitespace(s): @@ -408,6 +408,8 @@ class KernelDoc: # Place all potential outputs into an array self.entries =3D [] =20 + self.nested =3D NestedMatch() + # # We need Python 3.7 for its "dicts remember the insertion # order" guarantee @@ -505,6 +507,16 @@ class KernelDoc: # State flags self.state =3D state.NORMAL =20 + def apply_transforms(self, regex_xforms, nested_xforms, text): + """Apply a set of transforms to a block of text.""" + for search, subst in regex_xforms: + text =3D search.sub(subst, text) + + for search, sub in nested_xforms: + text =3D self.nested.sub(search, sub, text) + + return text.strip() + def push_parameter(self, ln, decl_type, param, dtype, org_arg, declaration_name): """ @@ -881,11 +893,9 @@ 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.apply_transforms(struct_xforms, struct_nested_pre= fixes, + members) =20 - nested =3D NestedMatch() - for search, sub in struct_nested_prefixes: - members =3D nested.sub(search, sub, members) # # Deal with embedded struct and union members, and drop enums enti= rely. # @@ -1088,7 +1098,9 @@ class KernelDoc: # # Apply the initial transformations. # - prototype =3D apply_transforms(function_xforms, prototype) + prototype =3D self.apply_transforms(function_xforms, + function_nested_prefixes, + 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 Sat Feb 7 15:09:57 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 1F83337BE6A; Thu, 29 Jan 2026 08:08:30 +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=1769674111; cv=none; b=IoCFvcEKlYZ56d57/GR4iJTUSShQen1H0q7sKjXzMynPtJCYWMQmEykCrobq+bfMQ7jTLEIHw0U84IlrezrInmRPBT7rCV+PhjplPblhskSSggKuSUBxGG1HSVJXpd56BhmuCW1/0LKZe8AS85VuWNgVOPvX9KG9URyFe1YGoqY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=Rc+cvBbCrvl5gHPyjY0jltfZsAtkaYF+V2rrj3nvojw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=LmcZ6q3ED1TFIWzFGME2IArt6iP702cqUQZwdJxZx20DEm7l3pEmN5HHE7kpmsEVtExROrlbvppeD1Ortq0r/DfsNtCmZcxByxgBD0Vlbh5D322vJpqiMj+0P68BXU0HXlZTsieOl/AU4jc03qM/M/8h6xZE2aq3pWNI9jBT31E= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=iy0rZPfm; 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="iy0rZPfm" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A3923C16AAE; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=Rc+cvBbCrvl5gHPyjY0jltfZsAtkaYF+V2rrj3nvojw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iy0rZPfmlg0iZMenj0l8iK0/UODQjeNmySHulwExq9W4tJTI4+X34weZAGmD+DlNG 02I7db29dVZWpQbhf1GTtI3P5f7kT/JU9Wc/HbbWmN3H95WvvGBR2ibZLVyLqh/D+L i0qnZB0TpPKMyZ33nDgcj0IHabhens0ostWAR8O+BKfI+3R2XDirm1wAq9AFva0d8J fL5dn2yA8P6xFQ3Wop2u62wPfIyPCel2SuzREMdnPrFq1PSDRx6FVd8/z+Sm+3PvSn 2O0vmumx1UuyTZ4OPgErcjRGPx3UlWsYr5T2jFieuW7V/KexcVsJoiLwjv4DeTZ5ol 9Us1o2dafHTUQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4m-0000000ERMv-3OoE; Thu, 29 Jan 2026 09:08:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 06/30] docs: kdoc_parser: use NestedMatch to handle __attribute__ on functions Date: Thu, 29 Jan 2026 09:07: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 Some annotations macros may have nested parenthesis, causing normal regex parsing to fail. The __attribute__ regex is currently very complex to try to avoid that, but it doesn't catch all cases. Ensure that the parenthesis will be properly handled by using the NestedMatch() logic. 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 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index ae5b2ef80f75..64165d8df84e 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -165,6 +165,7 @@ struct_nested_prefixes =3D [ # the start delimiter. # function_nested_prefixes =3D [ + (re.compile(r"__attribute__\s*\("), ""), ] =20 # @@ -195,7 +196,6 @@ function_xforms =3D [ (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+")= , ""), ] =20 # --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 52C9937BE87; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=Bp03FIBUc3j2Xn/dhSl/qKcJ1Wp9oly/9lR30+0B2MZ7EVZ8koIJ0OBEiAzabyI9hgAsnbFTnBfN6OJ/V0IqvFGdPNwncketweHM5R1IVs4YNJJVeqawqeP4NwP/TiT3Pmqy6q/mVzQ8BtWQCSzE8NYIBgI18uqvDQza2tL1ba8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=LW3FWQWxnWgJD3Z8QjxOsIjqHu4vcqWf8FWt35UhM3s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=CCdxuM14AwcALCE4tXN2qTJENOu5FPXBObydos69phpG5g9p9KP62TYLxUCnMPrxOHqy/eYg1frCpv0XIPnaLkfycRsYVEr++5jEZRRk8EhcQ5VWwexamgsN+ue3ZoDH4PpAWn65n55L8lbTBZ8x3mgTAB8743uJD5sOaZQtYeQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=IAFKwnn2; 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="IAFKwnn2" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BA308C2BCB2; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=LW3FWQWxnWgJD3Z8QjxOsIjqHu4vcqWf8FWt35UhM3s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=IAFKwnn2WQ2LTQ+V2Q6bxCu1p/XmRfCkKxyrmaMY0/iIIK8zb9g61njzm/YtULJT2 VE04xPo0K0jRcwe1wzCMhTt/HiiHk4To0HA5t7i/l5PuJKIC4pIUKaDLy5Qc1AUTjd QtiFiHcMEjLPFa5Nkg238OsY58LwWy0p56rUd14wBdWe/QvItPbNF3xGinJl60zO5Z NmMKteKPwesqWjRtpVvYwZVo3PR58s+RrFtF4dPEagC9OabwpinzbCNysJuq7LB+hj i2wKvNxjAA9JXTVY1BG1RckQo43m2+ftvaMG1Hp4pUK/WmyASxPbA/eFVARQVczxy/ 0nH7pY5/StvRg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4m-0000000ERMz-3W3o; Thu, 29 Jan 2026 09:08:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 07/30] docs: kdoc_parser: fix variable regexes to work with size_t Date: Thu, 29 Jan 2026 09:07:58 +0100 Message-ID: <1df8a82162411a720dfec076062263bc7cbbcfb7.1769673038.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. 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 | 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 64165d8df84e..201c4f7298d7 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1027,14 +1027,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 Sat Feb 7 15:09:57 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 5178D37BE83; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=muZl7lPR0o4mv44QJcvBkEZEYqWa3us0usSZMGlxkjFtjsDlUIdP5Jrk7kIdWJ/nRne1bE49SZLCgmc740M6WV1ZbMdOM9s/FNCutiWGlSxWB9xiAv65dNdaMvTeXw2J8xFdIRcjzWTne2YpOkWW0LlERvL7IHiPsCJSxiVur7c= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=Fd24Q1nDNP9DgJx33rkWp9Vbgr/MiR1kgk0MwpCT/0I=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=EloYk4eo+PAwXP/bBnAPSp60RJz3Vq7dYRcB2bvCYqy1cWyNdBK6z7PBPq0SmQ8OY1eK3zeMfkx8EoG1Bd+1xUJIVMASn5fqYLf315VbUiLNWjGdXxrnbyesTreaTm4j8jeFYluc32WfdWF+n+3chdZf50WQFnRSCuBJo8kHPBo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=EaJ+6SiK; 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="EaJ+6SiK" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BDF8BC2BCB1; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=Fd24Q1nDNP9DgJx33rkWp9Vbgr/MiR1kgk0MwpCT/0I=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=EaJ+6SiKajBaKm7SB7w2zP1dvwODnIAER/meOLX7nxnn6gLxkEb/B0RrT71TbfR0o 8+l/DWM0eX1DoNaxx9ftn4rvqpjh+HyHq5Apy/SfwhAY5jYvFFuuJRgMzi0h7hGLw2 q++w9Z3T0Hm17UiNNlfRvp7qcAwg0apFLthDKcxbw2inN6a3bp7vMS5H00xnLiJiqS 3eB+ceE70/UwK8xFXR+iDhLaS0Wi5cILTXVA12VJU857y20Nyud2cMJkDm5EVYia1+ xoBl/eZLtd/F7Yc9GMgh78TMTlBc0MezOO6B56B0cuzn5sThkQJBjgWiXLQedg7gUF 7PQDTIWFHAFog== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4m-0000000ERN3-3ecl; Thu, 29 Jan 2026 09:08:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 08/30] docs: kdoc_parser: fix the default_value logic for variables Date: Thu, 29 Jan 2026 09:07:59 +0100 Message-ID: <95b5345d74ad7c7e4898d022cb9195d0e2ac13cb.1769673038.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 201c4f7298d7..cbfdaba39494 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1035,9 +1035,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 Sat Feb 7 15:09:57 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 4D86337BE80; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=YJkwiLPb6FK9KXHOfpL81KWA+Hnh+N+fgvqpr6trXtkHQJepMJPzPbn9ExwbSAXHXXcz/bkrJ/eq5mtsSNvmBdEBY3CfoQt84WyKgZcuR7Jitlh+nWJnJCP6EYSP/wN5KfMlxi4XEbyIDzhAQQh32vNe88+HHBcdGjL5QTM//vo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=kiVn8gJsa15hW54tTb5XhUjmr8gdDA7uMvhSg2gJwFM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Ia8wndbQ9n1vGshpJAWrAaq6G1IyObiIU5bHUBc24ocp24fvdDA2aTzWU0qMLb/bq9DGHPv6gj3UNsgFW1uc5MNSaWlLywpzNC0KsXJMvmvMyn1zNB87dI72/ouJDrfpMUhzvieWGhFfEInEdOqqOxXz5hGaipIZaMdlIZQhK7c= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=rRYlmWIY; 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="rRYlmWIY" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B2B56C2BC87; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=kiVn8gJsa15hW54tTb5XhUjmr8gdDA7uMvhSg2gJwFM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rRYlmWIYtl28aLBPeHoJLrtt2o7YYwufJtc6iuVkWUG1kcg2h+bx6TSeifimrMMZ3 BzFdrpHZGcW/6s6aUTpU0RkDyo8zSxwnHpis+LRZ/mxjt9ealPBK6QJzycW8i2wWDq BT30MVkPtCNpDzaJGD7WSrMaghlK3yjAJhejnKH0pKvkl0nDj79Z3B459sXtxzTlSy addAj/WF4Y9eTx2S0eQjIHvUpXaJro11wnp6U7Dlt00mvx3Bx6TiMR2zasMYB+HT7a Jh9c8Pb/KhBzIQ7+Z76qlHXHkbGDI0Q6HHA+n3/jgQN51dF22SK9plrvInnLeaImDz 70bLoCC6p7JCQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4m-0000000ERN7-3mCH; Thu, 29 Jan 2026 09:08:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 09/30] docs: kdoc_parser: add some debug for variable parsing Date: Thu, 29 Jan 2026 09:08: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 This is a new parser that we're still fine-tuning. Add some extra debug messages to help addressing issues over there. 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 | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index cbfdaba39494..ccee4e0bcaab 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1033,11 +1033,19 @@ class KernelDoc: declaration_name =3D r.group(1) =20 default_val =3D r.group(2) + + self.config.log.debug("Variable proto parser: %s from '%s'", + r.groups(), proto) + else: r=3D KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_]*)?\s+(?:\*+)?(?:[\w= _]+)\s*[\d\]\[]*\s*(=3D.*)?") =20 if r.match(proto): default_val =3D r.group(1) + + if default_val: + self.config.log.debug("default: '%s'", default_val) + if not declaration_name: self.emit_msg(ln,f"{proto}: can't parse variable") return @@ -1045,6 +1053,9 @@ class KernelDoc: if default_val: default_val =3D default_val.lstrip("=3D").strip() =20 + self.config.log.debug("'%s' variable prototype: '%s', default: %s", + declaration_name, proto, default_val) + self.output_declaration("var", declaration_name, full_proto=3Dfull_proto, default_val=3Ddefault_val, --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 F0164369993; Thu, 29 Jan 2026 08:08:30 +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=1769674111; cv=none; b=I4PF1GY4h2cyiABg2W5h/vq/PgH2aZQMtT/BQWx7XBqvCBLps5jWTkQgu2JCDE+VQDCtw03dtFUlaker0lUo3impuUB9hN9s6lSbayTZNbB5hCbhDHub7+xd6W2Gimpu2Afv02DyB8/Fpv9Us5R0NvtGY6+wtlvbiplbYNObd8A= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=BGmC9Ub+EwkCy+50Wez7U2hU9ogTq3RfJ1GhpzG3syM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=a4Z26pxGt8xO87950o/ayPUrdsdwGefmmutSOn2CQbT+bbwJtoufJ2w0Z3nH9F1us559gJXv0LIYl5VrK8nJJ2U8F/ZclxjbyoOBWD5xQmfSj7KiQbTSb2UZ8CSefBM1AqPPmthu9dgCbDPibQVaZndy3aOPFeYsH2BsThxZOsQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=hn8T9IGP; 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="hn8T9IGP" Received: by smtp.kernel.org (Postfix) with ESMTPSA id AEC54C2BC9E; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=BGmC9Ub+EwkCy+50Wez7U2hU9ogTq3RfJ1GhpzG3syM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hn8T9IGPVjGyPPbYWb4NnckSfEsNfnGStNJhrzxSeaLckmjOD5mf0fJlZmaE9Wqmq z2oaFLFX8hzuBVYeBDzrNhAw1MKJtwfhMOAcOLV28e52Xo14wkVL3+certGE/6OIfr hPxxYPlH8qjRwSbutOYyTo6pn2H0kfipWlkH/L6WIiBW247YzoQv6Pr6Av+FJUMIC2 eVAI2XliVA32Qpq1Auy/s8+sqzWEEs/YCVI3WCIrGasq/18pNJcakGgn1RP0zPS+o8 3m7gnuHnhS1kjONaOIixk0dR68BItVApoNndkv6/nqHbZfgObTyzGEMvZRtwlqlbM0 wX1WfFnGY17MA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4m-0000000ERNB-3tor; Thu, 29 Jan 2026 09:08:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 10/30] docs: kdoc_parser: don't exclude defaults from prototype Date: Thu, 29 Jan 2026 09:08:01 +0100 Message-ID: <0c40c7f91dd5c95b1efcc0f2c0103f941f3c24d1.1769673038.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 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 ccee4e0bcaab..0b6cba442d72 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -207,7 +207,6 @@ var_xforms =3D [ (KernRe(r"(?://.*)$"), ""), (KernRe(r"(?:/\*.*\*/)"), ""), (KernRe(r";$"), ""), - (KernRe(r"=3D.*"), ""), ] =20 # --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 513083793B9; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=iy/ErCp33l3vTvtAgjHub0iXx4Bm/SfxlnOSlFnv4LsWWbtAqapxM5hbYobUCmWQwwAQJ4bs8E1p8hbe+M6snpn9rycXEp2+VOHmzw5zQzFLIrpMzb5khvZHCosbUrTZf5lusxlh9R3VI5T5L3BuoOl75r0IencgVmE+gB5cxnI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=+PHSHQk42n1s2eoXmKBeCEHsRg0AhUmcVaeG8R0cpiE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=iOlepQAK5OvQiPNOXPexWHTgR2tCrpGr43ndNF4cBwkUGy/Lmn8C0hSr4QAlg4S6Q2M+F73n5kiHkw7HBS69ew42zb7dEQf++cxfQjjU8mN8ql/4CPfCwTjX7g5N/qahGnGBg6Osp7f0SNRK2Xb/CspitA/8VE4w4CBtOAjIPKQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=maC+j0hn; 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="maC+j0hn" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B783FC2BCAF; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=+PHSHQk42n1s2eoXmKBeCEHsRg0AhUmcVaeG8R0cpiE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=maC+j0hnj48daFZ8ng1N2+Dhr0gXmdF5Aqm760IJ2bxebUBl3pXpyOaCZo5TOLpcn IkhsbrLqlgISNP7BK4HxZGS/wC52393Hqu752r7dwz2uwcE0UgsqEgf8I4w6QkpTvR zO5SBxLAC5X6LmYBUnqih4ID5SoZKccfIanf1ICyGDDg15aIQOQDcrhhJE0s0H4lhD 9LT10mZfR+Sdy4BSjUGvxct4kZ89OCUsXJ5hBwFlRyyKEUp5onfAw8iDMin87GMPqo OSvCg7qLVeNPWtAVEP2dQydfkutav+M6NUuiTA+lBI7silsWnPxs8sJUZAh0U81WzC ayaNzT6hHpUEg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4m-0000000ERNF-41KV; Thu, 29 Jan 2026 09:08:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 11/30] docs: kdoc_parser: fix parser to support multi-word types Date: Thu, 29 Jan 2026 09:08:02 +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 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 0b6cba442d72..21cc4e19a1e8 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1026,7 +1026,7 @@ 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) @@ -1037,7 +1037,7 @@ class KernelDoc: r.groups(), proto) =20 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 Sat Feb 7 15:09:57 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 4BC5037BE7A; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=IeVlk3+1dHjRyR4yQQRbDt4x2YgtH5B80zb45dvHk6dra5U6102JFG5iNMesgyDhrfH4sRaF1Kc/Eyu+bbFlXFILYEr2/bkghpufIh57L1Tslo2CBsaaxztZ4OOObhjliitYvORTOaffLQ9jfhMKDPGOpyDhZjzUjKQ9va4CziY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=YVVe7KRzqnppyn56cGxlJApAQyowTVAxdXTJwpP28d8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=s6RbTotBNaJk87h5iZ+qZEmgcNupSpTG540NAwqWTfN2DCnyTOW5u+a9ERGLWH21tzJtVb7zZc3fpX4C0j0wgTMwogrpyakmJJL4qfI0XrhFa4kpvH+nivN+MAVFacLrfMfYYurapXzl6ngmOuIufp4IsFJAuMV6rlWyMI7VoGM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=U/6AzwnP; 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="U/6AzwnP" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C08FBC2BCB4; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=YVVe7KRzqnppyn56cGxlJApAQyowTVAxdXTJwpP28d8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=U/6AzwnPbi0JtNsyush7PTt00zFhCG3tLQvlkFbZ9Jte2MVU70b/Do3DNn8kmsgMY QSCqZ5Tg5wk9tsYUvgDxQTcdusyCYJaLWYsgkc8Pl7b7mtQzdUQ3xMJE/9xkPQRRi7 ynY8C8TEvEOIp22i2fGdZGbdracy1kisBHqd6cySZnGw+G8uv25w9APtgCy9OBlSPE /trEApOqHAOlkp89lyOMFh8tfw6wevZ5OYaEKpdGk4EW90GJQBPCp+CcOZY3wvpMsq 9lcsha0MOmxO/0Fpba5X34F29QCtR8kERubCjdwt907RoDJdKrB1fL2c83b9txCdiA zxvRKXlRvI7VA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4m-0000000ERNJ-48s0; Thu, 29 Jan 2026 09:08:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Randy Dunlap , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Stephen Rothwell , Mauro Carvalho Chehab Subject: [PATCH v3 12/30] docs: kdoc_parser: ignore context analysis and lock attributes Date: Thu, 29 Jan 2026 09:08:03 +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 From: Randy Dunlap Drop all context analysis and lock (tracking) attributes to avoid kernel-doc warnings. Documentation/core-api/kref:328: ../include/linux/kref.h:72: WARNING: Inval= id C declaration: Expected end of definition. [error at 96] int kref_put_mutex (struct kref *kref, void (*release)(struct kref *kref)= , struct mutex *mutex) __cond_acquires(true# mutex) -------------------------------------------------------------------------= -----------------------^ Documentation/core-api/kref:328: ../include/linux/kref.h:94: WARNING: Inval= id C declaration: Expected end of definition. [error at 92] int kref_put_lock (struct kref *kref, void (*release)(struct kref *kref),= 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. 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 Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 21cc4e19a1e8..92b550189988 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -81,6 +81,8 @@ struct_xforms =3D [ (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), ' '), @@ -165,6 +167,16 @@ struct_nested_prefixes =3D [ # the start delimiter. # function_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"__attribute__\s*\("), ""), ] =20 @@ -195,6 +207,7 @@ function_xforms =3D [ (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__ +"), ""), ] =20 @@ -204,6 +217,8 @@ function_xforms =3D [ 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"(?://.*)$"), ""), (KernRe(r"(?:/\*.*\*/)"), ""), (KernRe(r";$"), ""), --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 5575D37BE8C; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=bCopkJ/UUYOBVM6BXxDk2IOD1spzrkeqF46FuKXX62YO/nxY6G8c1bbaq+y96yOvlFDElJ/+xiiu3tMvZxk2k4LI5ssbdjW510B0ALyRzcetVx5d9QD78oiylBMSEFEDtBtchjxJ6rUgi8m424ISvAszLY42srWVPHv65dnUfwE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=FAGo3vp1MYKDT8O2fN+VyX3S2nX5qeOzVDn265Hyrg0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=lLtaQd4wYlcFQsSQ8yrx/gIb4dACEkTgF+hXllofg1Nm5Ow7VQCiJlGmt3vw1BcZgJS4EL8Z9yNcwZ4WoFMnFNdkMet/BFnAsSQvO4CK4VUyTfpDkMGo8jycQroAvFxnw/bXgzYOjhrlrMUKb3Cnr5JXq0wDQeH40F0nTzerHDI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZYIXG4Pn; 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="ZYIXG4Pn" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C469FC2BCB5; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=FAGo3vp1MYKDT8O2fN+VyX3S2nX5qeOzVDn265Hyrg0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZYIXG4PntOUltCSEcvyS+98lAzjHGgYgoCfAR2ObOHOQwAoPHNqHuL+GENY8MpXYX aVrxzzSXeVGrTJP7ruAICt3nre+KhGAEQVhJDCoOKLkkKWCi0Va5XVXq8LhVAtfetW GwLNOXehMcLI4eZ97Xb2h2ko4fQAumc6/JMzBBr891wehhvVqPNH8XtJBVxJmkoLl0 3tlLkKoB88w3eSU5ZGSyt7HRB0k7eRUxCDZ8xisyLldDdwk4JyiXxt31gnZcGxH8bD 9NVS77OCFVPa+jYVkedLi2nc4cCqjH0yV180GVmB5oRJxGd3xkJVEmmGU6k4iene/+ ekd7boTnh2sjA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERNN-04ED; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 13/30] docs: kdoc_parser: add support for LIST_HEAD Date: Thu, 29 Jan 2026 09:08:04 +0100 Message-ID: <4f024c9e51d9354ccbf24443c88e1eb0bb5087c4.1769673038.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 92b550189988..33710c4be145 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -219,6 +219,7 @@ var_xforms =3D [ (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"(?:/\*.*\*/)"), ""), (KernRe(r";$"), ""), --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 568A537BE8F; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=Z4tKiGiqoDzHX6l6nWyqWhnsMn1BK72tJIL/6aCTog9T1sdiWVlI7rduA9T1FwgD9WKF1jgymxE1XpcXOfHl4ZsTQgsGwfiz2u5rVpQmOYDu8IgnLnRL+nQtIqjHnra6EqVoJivT/nATjr7k77M6dik0IYHaIyueKN0jphgIvAo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=E/NkbGhW79SHOexEJ6i7PkHNPXwMx9nBDdwcfT26Xts=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=TG4IS+HRcxmTbPj5CPL48N77ELy4LUCYs0xTPIa/FLIyltSy9bHzP6sCXM3YMa2v6FGzl3szus6tiqB1ori8LvdkWFQQv/HESoTUU1GWLT/yCjrIO5Y3Nqu2QyCyBS++qx6iaYQuQRJfLvUQ/ksaezNzH2xU6/WV2QMFnDboYiU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=REkXesK2; 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="REkXesK2" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C70ABC2BCB9; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=E/NkbGhW79SHOexEJ6i7PkHNPXwMx9nBDdwcfT26Xts=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=REkXesK2ak+UA0WRFomQIlfjRgBC3z0jjpTzLElphbdtS8ZGZEWHiM6vmT+PFIQul IadTKCJM2XLeOkykMUr4U10fj/gNhNjd4oXGv+Wi3zOx37a3epfq+rJayNLKcT37oM gL5/+mZBzb3ULTrBPWSDluE99AbKNIuyq/R3QcE/cRPAAWkmBivfBGMeFmJzoURW2i 6wZfcNuNSSXz1hm0dAKcbxPCOXS0DWlnUIrP/geT3GiFcB11Q8KSeCtiaO/QS/nMhb n1nlECpHcxaJD1YKJaWBwA85VWVnTCXqPeXlyEqchQ7CFbSdjuhZJ6SpufTTmCiMTp i1FHrzIOwVfMw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERNR-0Bdx; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Randy Dunlap , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Mauro Carvalho Chehab Subject: [PATCH v3 14/30] kdoc_parser: handle struct member macro VIRTIO_DECLARE_FEATURES(name) Date: Thu, 29 Jan 2026 09:08:05 +0100 Message-ID: <61cde5c7b7faa0becb45d9319abd6882395087e8.1769673038.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 --- 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 33710c4be145..db140363104a 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -152,6 +152,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]; }'), ] # # Struct regexes here are guaranteed to have the end delimiter matching --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 57A0A37BE94; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=Mx9NLK2nIiDlNEkOnowq9P+DjZc1PmtE0G34u4d8keg4efCSED/AeWaVoMAKSD60ENQ24mTiAVU7g9qykE95eE4IeNtYNwXoCjGjDwkrNrFvEPbWbJW/D1jrsGxUPwPExGkf7eWz1akMLsp48jnzm17ssbZQwMjcB8E1uW59jxA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=LaLUXoY/KS6WIRVp9iorgFncFjJ1rGpIWKLw4YbQxJU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=UXt5TrbD1X57TJxKIbwASpxxp5o6RDFFGisNRBE1a/+NIi8EOT54Wl5k/uZ6Rx8koBTDBsYntV7uaWzVLjj25KyDBqt205XZ70eCIPKt9F1jwvR6e/heiVDnpxV/xcY4eGXnUjlyQ7uq7/czzZmInIl4lCy4mZFlyHE14eHlTAM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=iWvhwl1b; 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="iWvhwl1b" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C5893C2BCB8; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=LaLUXoY/KS6WIRVp9iorgFncFjJ1rGpIWKLw4YbQxJU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iWvhwl1bfp2HBezorxauaO2EZmjPRMrkGOxSaekiDDkwvvj54BDshhDG+O7SVaA9C xdaxITXkK+MopAflWPI8De6K5bYS2ZxkJPqKMhFpSdRY/ZO2kYVYG9qIT0LrLz6/C1 svr53IqwZasCzcupbxTQhw8NWrQB2XViEOusMQch1adrBJUYq8Fp9hJNfSsWXCk1rG Q32rJBkRJegIt7DWiF+o1vjrt8lAmuOPrNT/kFCF4QyaMf0L1znAQPcqbY0Dpn20HY X4X+C+bpDUwRK8KLSikyO01ou2ABIiQr2he1mSqkdruUDwB3fnUJYzD/1R1M/ZNZsr GpTw9EisEz9rw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERNV-0IyM; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 15/30] docs: kdoc_re: properly handle strings and escape chars on it Date: Thu, 29 Jan 2026 09:08:06 +0100 Message-ID: <486ef8c6f1f066d495b23df2dcd450fa5c2bc3e7.1769673038.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 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 a0402c065d3a..1861799f1966 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -195,6 +195,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: @@ -208,6 +210,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 Sat Feb 7 15:09:57 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 5618737BE8D; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=IgY+Qe/Dek5GjaSQXxaxAppTUpzPNKGek3yfERPZsDooJ6K66YKRQt1gjeeRHMcWT/ZkDKYYJLIwAn0huqW59BIUmMDoRR/jTdIOzn2Coa5BP263/4wyivF6EWU99mQCJxZCihI5Q2PpV7XwlfvS53yDpyK20fwsPH3/FuXk+s0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=g8cGRz7h/9tP7TX4V9PxMZVBTj2F64+M2ftVKqF0XCA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=s29i0bcTIEMDw4ADwX89zjaly5mR4mPVqYnTROt6MGe2g92efGhi+2qODddOVBAUS7bRrlmMdH5DiJmhuUIOERIsvXrse9oMrmeDMSw1prJ4Ysp9Hb+DRTkjtaQYcqohAMQtJNgB+dxhr8b07h4z/pWLl6BnDs03YHAbKLkW+hs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=SiHnDL64; 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="SiHnDL64" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D7263C2BCFA; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=g8cGRz7h/9tP7TX4V9PxMZVBTj2F64+M2ftVKqF0XCA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=SiHnDL64Fb7vcErOt3fgGRtQCv0Y0HNgJJ3VKPWjXb/LMlum5XlBPW6ToArO9Tp6V ur60nJ9xts83zPp23GmZhMZxnDnm2BE6R1jNCPr8+N6AUk1ybesCXtubHIbV5qko+p B9EfjVe+rGe3CsQefkHQl9KhlrhWA6QQd7P+nvARpFZQGFg2bSFcbTpb9Hp+S+5MBI SVEjxVbVioIdihffhiFKBh3V28tp7eWcIZAtv/gfwct1wTfDnjHw8iEyJzC0ElyVB9 eP+tWD+2R8/vuL1I9OWXx+a0roZqs7ndKww36AoazQS/19akI7TCd51i/uOzLYXSAj cC6Sgm3eYuTQA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERNZ-0Q97; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 16/30] docs: kdoc_re: better show KernRe() at documentation Date: Thu, 29 Jan 2026 09:08:07 +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 __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 1861799f1966..3f405addcc58 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 Sat Feb 7 15:09:57 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 5181337BE84; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=HyIHJGBdQKE25Cmi6kFMuf9RFoOEre16hdlHHgQ/hoLxx7cV2NmamvpFYXIOUkeGeftMDcxhiwRy5l1EcANh8knrzj5lb/orps+QzGPi7tqlHm+EDP5d9FplvkfQqaDMFK8ou8rUIsjjpy92qS8frSoUNEILUVHwqC1BOwuab50= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=ceZVyyPX2HM3A215qLrOaX/Gfxk8tK5tZhLuxNFkn38=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=eAKIeRwbNI9k+ekQe4DOK9+iPwcxgvMDqf3RFa4/HTOCUFuQWmaamjOycGkvCIqi3jnWtHGAYCqpWhN9NC9nDJE6JVdCEIKtAXzKZqANI8Vu2PmkaB0U19wqHXzXXKv2S/D2SBlgKNChoLpWu5xUmmMvQJwHcVEN7Od31hxZ2io= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ClkZ5Aac; 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="ClkZ5Aac" Received: by smtp.kernel.org (Postfix) with ESMTPSA id DC7CAC2BCFB; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674110; bh=ceZVyyPX2HM3A215qLrOaX/Gfxk8tK5tZhLuxNFkn38=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ClkZ5AacxK6NDrStNwCjyJvXg1qxbkYQbqzXHd0p6ie26FisfEYXRx1Fve4+WqsCG g6PjeE7mgn/fxMdcinSrXRkXqvTRcYI0aTI02MMrd+RO6nQWx2MvRMNg4gPatHCNBX XzdcND/d/AYxjkLtNpBaIIpfsFeSqBKNLk+ZckxxX6lS5EOZelaPTmqxP1daprU72v 7QQbYWRYMS1IH5ihm1Ok1VznBJ1gRad8Q4+8gf1Q4PlorofDvarbqBU3LWTIQhjIVW OpygAxI1pZEpFjmERWxyQAlrD81lwSnJxebh38jf7AfqxclrgiKrBM6qP1yxnT0qN1 AQEpCw6tsVEDA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERNd-0XBz; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 17/30] docs: kdoc_re: don't recompile NextMatch regex every time Date: Thu, 29 Jan 2026 09:08:08 +0100 Message-ID: <168e559a46713f390c2984fc1c11e16e552ab0c1.1769673038.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 3f405addcc58..7b7ddc50ac36 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 Sat Feb 7 15:09:57 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 7187C37C0EB; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=TOd4AggQaMUJfoyo/8f4e8y8365XmchUXaaGEnN+IYIPLCkbAlLT1/OqE1T9PE3NI0je94cUpDzUU2/oih5g1DEAemraOPudjrMt5dLumaW+GpEQJuBUgJMYxZ2msRzRjAVyyc7kmrgLMVFc99UhuWP+mHzFdtjT3H9oVar8Xgw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=rCmGw1Wb+1Jckq+xhR2lN4gdNL9na4qiJFEWwkWiJR0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=m0VNCtN6Vu0Ec/iFJkl6sMcdnqKhBzjb7OhYhB8/FKCLkb0C4BrGsg11uKvvdf1W5U8IIm+EoFELYIuJKuMSDFOVnqLdeBFNA78AXG4cKFVlH/MlH//pAqnuZqFywW32OB+rtoeGvzrtBcjMPMm2ptvXRVv03hlOg32VUk0cBtc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=IUAsCq5q; 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="IUAsCq5q" Received: by smtp.kernel.org (Postfix) with ESMTPSA id E68C7C32781; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=rCmGw1Wb+1Jckq+xhR2lN4gdNL9na4qiJFEWwkWiJR0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=IUAsCq5qj7DiIxihFXTCS1JgP1c4yGGiUCww/qZKGIPCTSyxdMq+eAMsid9MGZ4DC RpdvbLFm2ssU03DL9ukwFVfGeTabsDkCSNjPNpbvcP/CvtIihKcWgMpjzuEQywSt80 h3kAKbpm1rr+cRlZfuRxabolUJ12tKi6lyPNtWNSUG/FLyB4ZxIrZRZ0V6NdvZeBdU 08CtnRJG7Fxs6NmE4RVKOoyNhp6dY6v14omfHGlaytD1BashrOX8Z3Snr7aUgs7Rmf zPjJ3h8P1OEN7y4S7XzrxynaOBumW/Rn9dEEENjcCR1R5QrzJyIiJLdF2MUVEr78LD V+dmCTRqoiLDA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERNh-0eOz; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 18/30] docs: kdoc_re: Change NestedMath args replacement to \0 Date: Thu, 29 Jan 2026 09:08:09 +0100 Message-ID: <04552ce2ac1a426e74bf7353e1ba1586e2af4f36.1769673038.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 | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index db140363104a..4d52a00acfad 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -160,7 +160,7 @@ struct_xforms =3D [ # is allowed. # struct_nested_prefixes =3D [ - (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 7b7ddc50ac36..8933e1a62776 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -289,8 +289,9 @@ class NestedMatch: It matches a regex that it is followed by a delimiter, replacing occurrences only if all delimiters are paired. =20 - if r'\1' is used, it works just like re: it places there the - matched paired data with the delimiter stripped. + if r'\0' is used, it works on a similar way of using re.group(0): + it places the entire args of the matched paired data, with the + delimiter stripped. =20 If count is different than zero, it will replace at most count items. @@ -306,9 +307,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 Sat Feb 7 15:09:57 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 4BBCD37BE78; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=sIOjgA7aqE7AQ4QqY0Ka8lGRVLZEue2yt7BJfQB0e4xeRKq8Ccx3jRSZfhsam4Xixg/yCRyiQoIWygQlzc69qHgIwmZJYUbUQk1/fXDLNAe7G8Q12uGewRCSNOlrM28uEnZGkeDz70Uxf8VUOLl+ZhIoFsqvw4XtSgZ49D+wePE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=ElI+oPOpkTCGBBK56tr/M/5Xy+VnpzXF5LiBdiYcH+E=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=n061IgjY1y0A9a+cPf1uYY+iNF5KzbXhCYe+iekndBMJ7jpnMGT1RLgiS6fm+F1fmxbVdmkDQTcCrP8BWdYmJNJOJ24Zg2RSnD7a1NOVf57IfdPx/r54ZBk3F+Uq+RrQEII/WA4BoKUjkl6SLJPSBTUwH1bTRipja8JSCjb394s= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=mGa/IjA6; 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="mGa/IjA6" Received: by smtp.kernel.org (Postfix) with ESMTPSA id E2990C2BD00; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=ElI+oPOpkTCGBBK56tr/M/5Xy+VnpzXF5LiBdiYcH+E=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=mGa/IjA6IrkzctpaQRF7WJ3fnbRtP65E7tTtaDPMQg998Y92UeyK9o8eqEjGJwb5J EiX7ZxSogjNP7Z61cRX0ZIa3UH7D9pqs8ou9uXRB4qo8+K+dmPnvrzX6TmA0g23nQO axCmJQWllSoUITerpG4mncDqA+DtQZ0bA52GlmRGyzUbvoWL9wtyPgu/zYWANqdQI5 dxNZXRC/0INgD2yCwsySphIBL+9mN6Y1v8K60v5DoaLt9e+kOx2ls6OI7pfbGDligR ZFEqvtFAG/pxuq+xak+HJ/xovQWBhy1oKwLDq0GAt+Z7WE/wEEY2HyO6hYu6vGwACw cG/AD0XRlfqkg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERNl-0liZ; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 19/30] docs: kdoc_re: make NextedMatch use KernRe Date: Thu, 29 Jan 2026 09:08:10 +0100 Message-ID: <8a7da8d12e69a5a70d63f85a3d4ea11af6ac782a.1769673038.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 Instead of using re_compile, let's create the class with the rejex and use KernRe to keep it cached. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 55 ++++++++-------------------- tools/lib/python/kdoc/kdoc_re.py | 22 ++++++++--- 2 files changed, 32 insertions(+), 45 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 4d52a00acfad..3a5614106af7 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -153,32 +153,7 @@ struct_xforms =3D [ (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]; }'), -] -# -# Struct 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 [ - (re.compile(r'\bSTRUCT_GROUP\('), r'\0'), -] - -# -# Function Regexes here are guaranteed to have the end delimiter matching -# the start delimiter. -# -function_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"__attribute__\s*\("), ""), + (NestedMatch(r'\bSTRUCT_GROUP\('), r'\0'), ] =20 # @@ -210,6 +185,17 @@ function_xforms =3D [ (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__ +"), ""), + (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"__attribute__\s*\("), ""), ] =20 # @@ -230,7 +216,6 @@ var_xforms =3D [ # Ancillary functions # =20 - multi_space =3D KernRe(r'\s\s+') def trim_whitespace(s): """ @@ -424,8 +409,6 @@ class KernelDoc: # Place all potential outputs into an array self.entries =3D [] =20 - self.nested =3D NestedMatch() - # # We need Python 3.7 for its "dicts remember the insertion # order" guarantee @@ -523,14 +506,11 @@ class KernelDoc: # State flags self.state =3D state.NORMAL =20 - def apply_transforms(self, regex_xforms, nested_xforms, text): + def apply_transforms(self, xforms, text): """Apply a set of transforms to a block of text.""" - for search, subst in regex_xforms: + for search, subst in xforms: text =3D search.sub(subst, text) =20 - for search, sub in nested_xforms: - text =3D self.nested.sub(search, sub, text) - return text.strip() =20 def push_parameter(self, ln, decl_type, param, dtype, @@ -909,8 +889,7 @@ class KernelDoc: # Go through the list of members applying all of our transformatio= ns. # members =3D trim_private_members(members) - members =3D self.apply_transforms(struct_xforms, struct_nested_pre= fixes, - members) + members =3D self.apply_transforms(struct_xforms, members) =20 # # Deal with embedded struct and union members, and drop enums enti= rely. @@ -1125,9 +1104,7 @@ class KernelDoc: # # Apply the initial transformations. # - prototype =3D self.apply_transforms(function_xforms, - function_nested_prefixes, - prototype) + prototype =3D self.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) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 8933e1a62776..e34d55c25680 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,11 +281,11 @@ 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): + def sub(self, sub, line, count=3D0): """ This is similar to re.sub: =20 @@ -301,7 +304,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 @@ -328,3 +331,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 Sat Feb 7 15:09:57 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 7197E37C0EC; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=sNP3/Fgmm063FsZBevEIiKYpcxmduTbaJi1UP5+/HlLnzCt75S13epP4yxJLCfiOu4O7DPgwXymbjZWmqURBZIvCxvAGmwxDovC8SMJkx9A3K0qaA1o/v8+SeEsONH5BW3VkViao/E2oDT4zL/bN3NFdbzelvhQ0Hgd9f7AwdpY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=IMy+0Ya2RXQo7v/hj8y/wU7iFOGEnBMPK5mE8t6wErI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=DscttxlNwnsTzvA4h2BiRC48zCbRBv8EiBj7estSen0luyJyfxFwlkeAPn/LBrrDFnkvJAjM7AMqEyYsr2WksDzpFBDmhEoxdWTNV+MXrEGdVnXH7+Y3OHeevq4/sgjXXIWeeGbRL8M8fjKVRtddnSz76JrKzIqWiRBMCSr5XUM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=CVDoK7RV; 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="CVDoK7RV" Received: by smtp.kernel.org (Postfix) with ESMTPSA id F06D0C4AF10; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=IMy+0Ya2RXQo7v/hj8y/wU7iFOGEnBMPK5mE8t6wErI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=CVDoK7RV2De5lMoh9xFIjFW36Xn4xiO+ZCn9lNN83XJWKr7vlvmzvYVCvMc3GUAld Sdy6KYa7nHzCbYjuu3w7YHbw3wLoyozY1UZl54hlwCKezmMqqJOlI2qxgGz4ZSVBeG G8KIqX5PzQEHuN2F7JQkrV3i/C+dWyfps/nxxrvOrtSb5DawA0t0/NiGcO0MXaLN5F L50AO1wMZ8tzN3wUOjqebmi6TU8FtVXhg45aHHOlm41GiPQe/RxP84iS7eQY3qR/1F oWaekbBFNJHH8DERwfqpBkLqh46fyrhbBKkVfEed0EJZS1T/VyShSIBy1u14nqB4AU TEs0JQjjqrNEw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERNp-0t7G; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 20/30] docs: kdoc_re: add support on NestedMatch for argument replacement Date: Thu, 29 Jan 2026 09:08:11 +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 Currently, NestedMatch has very limited support for aguments replacement: it is all or nothing. Add support to allow replacing individual arguments as well. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 84 ++++++++++++++++++++++---------- 1 file changed, 59 insertions(+), 25 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index e34d55c25680..858cc688a58f 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -177,29 +177,6 @@ class NestedMatch: will ignore the search string. """ =20 - # TODO: make NestedMatch handle multiple match groups - # - # Right now, regular expressions to match it are defined only up to - # the start delimiter, e.g.: - # - # \bSTRUCT_GROUP\( - # - # is similar to: STRUCT_GROUP\((.*)\) - # 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'). - # - # It would be nice to change such definition to support multiple - # match groups, allowing a regex equivalent to: - # - # FOO\((.*), (.*), (.*)\) - # - # it is probably easier to define it not as a regular expression, but - # with some lexical definition like: - # - # FOO(arg1, arg2, arg3) - def __init__(self, regex): self.regex =3D KernRe(regex) =20 @@ -285,6 +262,59 @@ class NestedMatch: =20 yield line[t[0]:t[2]] =20 + @staticmethod + def _split_args(all_args, delim=3D","): + """ + Helper method to split comma-separated function arguments + or struct elements, if delim is set to ";". + + It returns a list of arguments that can be used later on by + the sub() method. + """ + args =3D [all_args] + stack =3D [] + arg_start =3D 0 + string_char =3D None + escape =3D False + + for idx, d in enumerate(all_args): + 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 DELIMITER_PAIRS: + end =3D DELIMITER_PAIRS[d] + + stack.append(end) + continue + + if stack and d =3D=3D stack[-1]: + stack.pop() + continue + + if d =3D=3D delim and not stack: + args.append(all_args[arg_start:idx].strip()) + arg_start =3D idx + 1 + + # Add the last argument (if any) + last =3D all_args[arg_start:].strip() + if last: + args.append(last) + + return args + def sub(self, sub, line, count=3D0): """ This is similar to re.sub: @@ -310,9 +340,13 @@ class NestedMatch: # Value, ignoring start/end delimiters value =3D line[end:pos - 1] =20 - # replaces \0 at the sub string, if \0 is used there + # replace arguments new_sub =3D sub - new_sub =3D new_sub.replace(r'\0', value) + if "\\" in sub: + args =3D self._split_args(value) + + new_sub =3D re.sub(r'\\(\d+)', + lambda m: args[int(m.group(1))], new_sub) =20 out +=3D new_sub =20 --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 771F837C0F5; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=fR6MOJ3rNROAAOMNHgffQ25/kB74degjPmxVwVRjPEeVI1GmXOD6t3k3xYF9kt8LCvLYvWhRD1bcDGkUMC3QO4m/8Rj0cJlQcycqlEtsGYUbVKVXASuWncfQ7fSA6aySgBjXoGxjEMpPeQ7aoKSSCh+sE78/1YPfuslMb1n5Abw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=JgAESjeyMdGBTP/DT74Q19UkIkpbBQsD4O6RYrpw4MQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=kBl/1VlYbSxcF0P45YSpQvNYzz8/YogVfgoBthL2vgXKbZ4OVn1Zxr4alOUePkW7XAgOokgTvE6Jz+dWiLCSm3a9etHlovF0R4WyUunml4v8emMO+HBNmeklmkTc796sI7hsw+JQdNJjk6hNRGhrrlQmdDoML0mZbGbvuyZRKU0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=D2zyGueR; 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="D2zyGueR" Received: by smtp.kernel.org (Postfix) with ESMTPSA id EE344C4AF0C; Thu, 29 Jan 2026 08:08:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=JgAESjeyMdGBTP/DT74Q19UkIkpbBQsD4O6RYrpw4MQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=D2zyGueRbOPclnPG8XRPjw3lhO3DOAGl1Rn2G0LlMbcqOxo/UY8kBByIuhqQ4tf98 9np/8OE76s9sFyo1IMRcrtsxEFJ5PlTc9FlK8guKUN8dt4bCMXNKniweFqzGAcDqaL gztN0hEK2OEj0idEE3Gbp5J/CVyJwX0cNSOztv14ImKql7Qj7TE7ItsQqw64Box4HK XRkkB7hWm9o0bmNIvBueyshxokO1tsQOOzk/eLa+qLkt9TU71ZO7TQ9XseRUj3M4UO E7aPNlLyPcoQ+GFS1ov04likgEsZ2zDNwYMuohsFL/yfeMLz5M4v62PzwrkLpKF6LL PCT1BLaIRaIBA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERNt-10f1; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap , Shuah Khan Subject: [PATCH v3 21/30] docs: python: add helpers to run unit tests Date: Thu, 29 Jan 2026 09:08:12 +0100 Message-ID: <3f9d100e35fb68fea8446de8984dd2de1f9b4f22.1769673038.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 While python internal libraries have support for unit tests, its output is not nice. Add a helper module to improve its output. I wrote this module last year while testing some scripts I used internally. The initial skeleton was generated with the help of LLM tools, but it was higly modified to ensure that it will work as I would expect. Signed-off-by: Mauro Carvalho Chehab --- Documentation/tools/python.rst | 2 + Documentation/tools/unittest.rst | 24 ++ tools/lib/python/unittest_helper.py | 348 ++++++++++++++++++++++++++++ 3 files changed, 374 insertions(+) create mode 100644 Documentation/tools/unittest.rst create mode 100755 tools/lib/python/unittest_helper.py diff --git a/Documentation/tools/python.rst b/Documentation/tools/python.rst index 1444c1816735..3b7299161f20 100644 --- a/Documentation/tools/python.rst +++ b/Documentation/tools/python.rst @@ -11,3 +11,5 @@ Python libraries feat kdoc kabi + + unittest diff --git a/Documentation/tools/unittest.rst b/Documentation/tools/unittes= t.rst new file mode 100644 index 000000000000..14a2b2a65236 --- /dev/null +++ b/Documentation/tools/unittest.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Python unittest +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Checking consistency of python modules can be complex. Sometimes, it is +useful to define a set of unit tests to help checking them. + +While the actual test implementation is usecase dependent, Python already +provides a standard way to add unit tests by using ``import unittest``. + +Using such class, requires setting up a test suite. Also, the default form= at +is a little bit ackward. To improve it and provide a more uniform way to +report errors, some unittest classes and functions are defined. + + +Unittest helper module +=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.unittest_helper + :members: + :show-inheritance: + :undoc-members: diff --git a/tools/lib/python/unittest_helper.py b/tools/lib/python/unittes= t_helper.py new file mode 100755 index 000000000000..d2efb78d8561 --- /dev/null +++ b/tools/lib/python/unittest_helper.py @@ -0,0 +1,348 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright(c) 2025-2026: Mauro Carvalho Chehab . +# +# pylint: disable=3DC0103,R0912,R0914,E1101 + +""" +Provides helper functions and classes execute python unit tests. + +Those help functions provide a nice colored output summary of each +executed test and, when a test fails, it shows the different in diff +format when running in verbose mode, like:: + + $ tools/unittests/nested_match.py -v + ... + Traceback (most recent call last): + File "/new_devel/docs/tools/unittests/nested_match.py", line 69, in te= st_count_limit + self.assertEqual(replaced, "bar(a); bar(b); foo(c)") + ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + AssertionError: 'bar(a) foo(b); foo(c)' !=3D 'bar(a); bar(b); foo(c)' + - bar(a) foo(b); foo(c) + ? ^^^^ + + bar(a); bar(b); foo(c) + ? ^^^^^ + ... + +It also allows filtering what tests will be executed via ``-k`` parameter. + +Typical usage is to do:: + + from unittest_helper import run_unittest + ... + + if __name__ =3D=3D "__main__": + run_unittest(__file__) + +If passing arguments is needed, on a more complex scenario, it can be +used like on this example:: + + from unittest_helper import TestUnits, run_unittest + ... + env =3D {'sudo': ""} + ... + if __name__ =3D=3D "__main__": + runner =3D TestUnits() + base_parser =3D runner.parse_args() + base_parser.add_argument('--sudo', action=3D'store_true', + help=3D'Enable tests requiring sudo privil= eges') + + args =3D base_parser.parse_args() + + # Update module-level flag + if args.sudo: + env['sudo'] =3D "1" + + # Run tests with customized arguments + runner.run(__file__, parser=3Dbase_parser, args=3Dargs, env=3Denv) +""" + +import argparse +import atexit +import os +import re +import unittest +import sys + +from unittest.mock import patch + + +class Summary(unittest.TestResult): + """ + Overrides ``unittest.TestResult`` class to provide a nice colored + summary. When in verbose mode, displays actual/expected difference in + unified diff format. + """ + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + + #: Dictionary to store organized test results. + self.test_results =3D {} + + #: max length of the test names. + self.max_name_length =3D 0 + + def startTest(self, test): + super().startTest(test) + test_id =3D test.id() + parts =3D test_id.split(".") + + # Extract module, class, and method names + if len(parts) >=3D 3: + module_name =3D parts[-3] + else: + module_name =3D "" + if len(parts) >=3D 2: + class_name =3D parts[-2] + else: + class_name =3D "" + + method_name =3D parts[-1] + + # Build the hierarchical structure + if module_name not in self.test_results: + self.test_results[module_name] =3D {} + + if class_name not in self.test_results[module_name]: + self.test_results[module_name][class_name] =3D [] + + # Track maximum test name length for alignment + display_name =3D f"{method_name}:" + + self.max_name_length =3D max(len(display_name), self.max_name_leng= th) + + def _record_test(self, test, status): + test_id =3D test.id() + parts =3D test_id.split(".") + if len(parts) >=3D 3: + module_name =3D parts[-3] + else: + module_name =3D "" + if len(parts) >=3D 2: + class_name =3D parts[-2] + else: + class_name =3D "" + method_name =3D parts[-1] + self.test_results[module_name][class_name].append((method_name, st= atus)) + + def addSuccess(self, test): + super().addSuccess(test) + self._record_test(test, "OK") + + def addFailure(self, test, err): + super().addFailure(test, err) + self._record_test(test, "FAIL") + + def addError(self, test, err): + super().addError(test, err) + self._record_test(test, "ERROR") + + def addSkip(self, test, reason): + super().addSkip(test, reason) + self._record_test(test, f"SKIP ({reason})") + + def printResults(self): + """ + Print results using colors if tty. + """ + # Check for ANSI color support + use_color =3D sys.stdout.isatty() + COLORS =3D { + "OK": "\033[32m", # Green + "FAIL": "\033[31m", # Red + "SKIP": "\033[1;33m", # Yellow + "PARTIAL": "\033[33m", # Orange + "EXPECTED_FAIL": "\033[36m", # Cyan + "reset": "\033[0m", # Reset to default terminal col= or + } + if not use_color: + for c in COLORS: + COLORS[c] =3D "" + + # Calculate maximum test name length + if not self.test_results: + return + try: + lengths =3D [] + for module in self.test_results.values(): + for tests in module.values(): + for test_name, _ in tests: + lengths.append(len(test_name) + 1) # +1 for colon + max_length =3D max(lengths) + 2 # Additional padding + except ValueError: + sys.exit("Test list is empty") + + # Print results + for module_name, classes in self.test_results.items(): + print(f"{module_name}:") + for class_name, tests in classes.items(): + print(f" {class_name}:") + for test_name, status in tests: + # Get base status without reason for SKIP + if status.startswith("SKIP"): + status_code =3D status.split()[0] + else: + status_code =3D status + color =3D COLORS.get(status_code, "") + print( + f" {test_name + ':':<{max_length}}{color}{s= tatus}{COLORS['reset']}" + ) + print() + + # Print summary + print(f"\nRan {self.testsRun} tests", end=3D"") + if hasattr(self, "timeTaken"): + print(f" in {self.timeTaken:.3f}s", end=3D"") + print() + + if not self.wasSuccessful(): + print(f"\n{COLORS['FAIL']}FAILED (", end=3D"") + failures =3D getattr(self, "failures", []) + errors =3D getattr(self, "errors", []) + if failures: + print(f"failures=3D{len(failures)}", end=3D"") + if errors: + if failures: + print(", ", end=3D"") + print(f"errors=3D{len(errors)}", end=3D"") + print(f"){COLORS['reset']}") + + +def flatten_suite(suite): + """Flatten test suite hierarchy.""" + tests =3D [] + for item in suite: + if isinstance(item, unittest.TestSuite): + tests.extend(flatten_suite(item)) + else: + tests.append(item) + return tests + + +class TestUnits: + """ + Helper class to set verbosity level. + + This class discover test files, import its unittest classes and + executes the test on it. + """ + def parse_args(self): + """Returns a parser for command line arguments.""" + parser =3D argparse.ArgumentParser(description=3D"Test runner with= regex filtering") + parser.add_argument("-v", "--verbose", action=3D"count", default= =3D1) + parser.add_argument("-f", "--failfast", action=3D"store_true") + parser.add_argument("-k", "--keyword", + help=3D"Regex pattern to filter test methods") + return parser + + def run(self, caller_file=3DNone, pattern=3DNone, + suite=3DNone, parser=3DNone, args=3DNone, env=3DNone): + """ + Execute all tests from the unity test file. + + It contains several optional parameters: + + ``caller_file``: + - name of the file that contains test. + + typical usage is to place __file__ at the caller test, e.g.= :: + + if __name__ =3D=3D "__main__": + TestUnits().run(__file__) + + ``pattern``: + - optional pattern to match multiple file names. Defaults + to basename of ``caller_file``. + + ``suite``: + - an unittest suite initialized by the caller using + ``unittest.TestLoader().discover()``. + + ``parser``: + - an argparse parser. If not defined, this helper will create + one. + + ``args``: + - an ``argparse.Namespace`` data filled by the caller. + + ``env``: + - environment variables that will be passed to the test suite + + At least ``caller_file`` or ``suite`` must be used, otherwise a + ``TypeError`` will be raised. + """ + if not args: + if not parser: + parser =3D self.parse_args() + args =3D parser.parse_args() + + if not caller_file and not suite: + raise TypeError("Either caller_file or suite is needed at Test= Units") + + if env: + patcher =3D patch.dict(os.environ, env) + patcher.start() + # ensure it gets stopped after + atexit.register(patcher.stop) + + verbose =3D args.verbose + + if verbose >=3D 2: + unittest.TextTestRunner(verbosity=3Dverbose).run =3D lambda su= ite: suite + + # Load ONLY tests from the calling file + if not suite: + if not pattern: + pattern =3D caller_file + + loader =3D unittest.TestLoader() + suite =3D loader.discover(start_dir=3Dos.path.dirname(caller_f= ile), + pattern=3Dos.path.basename(caller_file= )) + + # Flatten the suite for environment injection + tests_to_inject =3D flatten_suite(suite) + + # Filter tests by method name if -k specified + if args.keyword: + try: + pattern =3D re.compile(args.keyword) + filtered_suite =3D unittest.TestSuite() + for test in tests_to_inject: # Use the pre-flattened list + method_name =3D test.id().split(".")[-1] + if pattern.search(method_name): + filtered_suite.addTest(test) + suite =3D filtered_suite + except re.error as e: + sys.stderr.write(f"Invalid regex pattern: {e}\n") + sys.exit(1) + else: + # Maintain original suite structure if no keyword filtering + suite =3D unittest.TestSuite(tests_to_inject) + + if verbose >=3D 2: + resultclass =3D None + else: + resultclass =3D Summary + + runner =3D unittest.TextTestRunner(verbosity=3Dargs.verbose, + resultclass=3Dresultclass, + failfast=3Dargs.failfast) + result =3D runner.run(suite) + if resultclass: + result.printResults() + + sys.exit(not result.wasSuccessful()) + + +def run_unittest(fname): + """ + Basic usage of TestUnits class. + + Use it when there's no need to pass any extra argument to the tests + with. The recommended way is to place this at the end of each + unittest module:: + + if __name__ =3D=3D "__main__": + run_unittest(__file__) + """ + TestUnits().run(fname) --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 7E5AC37C0FA; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=A09BdnmfPJc0TAO1Md5hx1cpAXR4lhb6Gvk2KyJPDiQZVnIZ4jNi2DSQomEjv2aq6pRAUbeH3Iz0oUdPbpHsTStsREwlI9gaoxZS2xoFq0vX+rpFONDsC4nouG4oxFDYkmFVDMZvtcXuXO9lqxTpSTdpSnEGcZXCKmu4wQ4j1UI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=pYNTYqwz57IhqZvQF9WXqa3KlEvEIfaBjfkBtr3E1OY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=HhsrWi2SOWTwxruo/HrkmqnGyQG8pzE5zZByBeYoAFa3W+2Kih8+/EIBXhbGl16CSlyfBtHujsndAOplJS4Gn1nxOYRh1Yg04MA12H8pWb8OOYsgO5bKJ4HjTII4OsvaRHTaNgfEQRxieIymG59w110vRM6iHKmURDi69OeWNDA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=uW8B/0Tm; 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="uW8B/0Tm" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 077F2C4AF15; Thu, 29 Jan 2026 08:08:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=pYNTYqwz57IhqZvQF9WXqa3KlEvEIfaBjfkBtr3E1OY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uW8B/0TmU+ij8VUsAbOrTXbaACsean5t2ynC6xDR65lgm2Q/5wrqHpkvIFIEV96Kx 8iGVj5pjlt2Y2CDNqo0KAThr0o32Oklsb0dm6uPXfAgEj/O9gy+OSBZoVmEBk5O2ZV upe2NH1GpIAhCW9dDiILfJB1X++SgIAcX97MjNIxwkA8aWEdqBgPlm0w7SVRM8ID1e sTgeTJJdiJ6UGu7dY3NLbVBqD00nmGkJ6IVBtNnxcwLcFaitZDKqWakkYWywbro/0s gy5LFWRbjG3RiZf/yiYfq/uM0umQauftDe9ZtNVlU1OqZ06mQWTVoipbzFUHINVX4P rpEF/A2VNyxug== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERNy-19QK; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Alexander Lobakin , Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, "David S. Miller" , Alexei Starovoitov , Daniel Borkmann , Jakub Kicinski , Jesper Dangaard Brouer , John Fastabend , Mauro Carvalho Chehab , Randy Dunlap , Richard Cochran , Stanislav Fomichev Subject: [PATCH v3 22/30] unittests: add tests for NestedMatch class Date: Thu, 29 Jan 2026 09:08:13 +0100 Message-ID: <89183ce52ea170e30993e28bf270bfda4ca659dd.1769673038.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 NestedMatch logic is complex enough to justify tests to ensure that it is doing its job. Add unittests to check the functionality provided by NestedMatch by replicating expected patterns. The NestedMatch class handles with complex macros. Add an unittest to check if its doing the right thing and detect eventual regressions as we improve its code. LLMs are pretty good writing unit tests, as those are just repetitive patterns that are built from the existing code. To speedup writing this one, I used gpt-oss:latest running on my local GPU, feeding it with my class and with replacement patterns from the kernel. I highly modified the generated code, though to ensure that the testset is representative and that all tests pass. $ tools/unittests/nested_match.py Ran 35 tests in 0.001s OK nested_match: TestStructGroup: test_struct_group_01: OK test_struct_group_02: OK test_struct_group_03: OK test_struct_group_04: OK test_struct_group_05: OK test_struct_group_06: OK test_struct_group_07: OK test_struct_group_08: OK test_struct_group_09: OK test_struct_group_10: OK test_struct_group_11: OK test_struct_group_12: OK test_struct_group_13: OK test_struct_group_14: OK test_struct_group_15: OK test_struct_group_16: OK test_struct_group_17: OK test_struct_group_18: OK test_struct_group_19: OK test_struct_group_sub: OK TestSubMacros: test_acquires_multiple: OK test_acquires_nested_paren: OK test_acquires_simple: OK test_mixed_macros: OK test_must_hold: OK test_must_hold_shared: OK test_no_false_positive: OK test_no_macro_remains: OK TestSubReplacement: test_sub_count_parameter: OK test_sub_mixed_placeholders: OK test_sub_multiple_placeholders: OK test_sub_no_placeholder: OK test_sub_single_placeholder: OK test_sub_with_capture: OK test_sub_zero_placeholder: OK Ran 35 tests Signed-off-by: Mauro Carvalho Chehab --- tools/unittests/nested_match.py | 589 ++++++++++++++++++++++++++++++++ 1 file changed, 589 insertions(+) create mode 100755 tools/unittests/nested_match.py diff --git a/tools/unittests/nested_match.py b/tools/unittests/nested_match= .py new file mode 100755 index 000000000000..570e98730b28 --- /dev/null +++ b/tools/unittests/nested_match.py @@ -0,0 +1,589 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright(c) 2026: Mauro Carvalho Chehab . +# +# pylint: disable=3DC0413,R0904 + + +""" +Unit tests for kernel-doc NestedMatch. +""" + +import os +import re +import sys +import unittest + +# Import Python modules + +SRC_DIR =3D os.path.dirname(os.path.realpath(__file__)) +sys.path.insert(0, os.path.join(SRC_DIR, "../lib/python")) + +from kdoc.kdoc_re import NestedMatch +from unittest_helper import run_unittest + +# ------------------------------------------------------------------------= -- +# Verify if struct_group matches are properly handled +# ------------------------------------------------------------------------= -- + + +class TestStructGroup(unittest.TestCase): + """ + Test diferent struct_group patterns. + + Please notice that in this class, there are multiple whitespaces on + some places. That's because it tries to mimic how kernel-doc parser + internally works. + """ + + @classmethod + def setUpClass(cls): + """ + Define a NestedMatch to be used for all tests picking all + struct_group macros. + """ + cls.matcher =3D NestedMatch(r"\bstruct_group[\w\_]*\(") + + def _check_matches(self, line: str, expected_count: int): + """count and validate each match""" + + matches =3D list(self.matcher.search(line)) + self.assertEqual(len(matches), expected_count, + msg=3Df"Expected {expected_count} matches, got {l= en(matches)}") + + for m in matches: + self.assertTrue(m.startswith("struct_group") and "(" in m, + msg=3Df"Match does not start correctly: {m!r}") + self.assertTrue(m.endswith(")"), + msg=3Df"Match does not end correctly: {m!r}") + + def test_struct_group_01(self): + """one struct_group with nested delimiters.""" + line =3D ( + "__be16 id; struct_group(body, __be16 epl_len; u8 lpl_len; u8" + " chk_code; u8 resv1; u8 resv2; u8" + " payload[ETHTOOL_CMIS_CDB_LPL_MAX_PL_LENGTH]; ); u8 *epl;" + ) + self._check_matches(line, 1) + + def test_struct_group_02(self): + """two struct_group_tagged, one per page_pool_params.""" + line =3D ( + "struct_group_tagged(page_pool_params_fast, fast, unsigned int= " + " order; unsigned int pool_size; int nid; struc= t" + " device *dev; struct napi_struct *napi; enum dma_data_direc= tion" + " dma_dir; unsigned int max_len; unsigned int offset; );" + " struct_group_tagged(page_pool_params_slow, slow, struct" + " net_device *netdev; unsigned int queue_idx; unsigned int " + " flags;)" + ) + self._check_matches(line, 2) + + def test_struct_group_03(self): + """two struct_group_tagged, one with nested structs.""" + line =3D ( + "struct_group_tagged(libeth_xskfq_fp, fp, struct xsk_buff_pool= " + " *pool; struct libeth_xdp_buff **fqes; void = " + " *descs; u32 ntu; u32 " + " count; );u32 pending; u32 = " + " thresh; u32 buf_len; int = " + " nid;" + ) + self._check_matches(line, 1) + + def test_struct_group_04(self): + """one struct_group_tagged with many fields.""" + line =3D ( + "struct_group_tagged(libeth_fq_fp, fp, struct page_pool " + " *pp; struct libeth_fqe *fqes; u32 " + " truesize; u32 count; );enum libeth_fqe_t= ype " + " type:2; bool hsplit:1; bool = " + " xdp:1; u32 buf_len; int = " + " nid;" + ) + self._check_matches(line, 1) + + def test_struct_group_05(self): + """long line with a struct_group(priv_flags_fast).""" + line =3D ( + " struct_group(priv_flags_fast, unsigned long " + " priv_flags:32; unsigned long lltx:1; unsigned long= " + " netmem_tx:1; ); const struct net_device_ops *netdev_op= s;" + " const struct header_ops *header_ops; struct netdev_queue " + " *_tx; netdev_features_t gso_partial_features; unsigned= int" + " real_num_tx_queues; unsigned int " + " gso_max_size; unsigned int gso_ipv4_max_size; u16= " + " gso_max_segs; s16 " + " num_tc;unsigned int mtu; unsigned short " + " needed_headroom; struct netdev_tc_txq " + " tc_to_txq[TC_MAX_QUEUE]; #ifdef CONFIG_XPS; struct xps_dev_m= aps " + " *xps_maps[XPS_MAPS_MAX]; #endif; #ifdef CONFIG_NETFILTER_EGR= ESS;" + " struct nf_hook_entries *nf_hooks_egress; #endif; #ifdef" + " CONFIG_NET_XGRESS; struct bpf_mprog_entry *tcx_egress; #end= if;" + " union { struct pcpu_lstats __percpu *lstats; str= uct" + " pcpu_sw_netstats __percpu *tstats; struct pcpu_dstats" + " __percpu *dstats; }; unsigned long sta= te;" + " unsigned int flags; unsigned short " + " hard_header_len; netdev_features_t features; struct" + " inet6_dev *ip6_ptr; struct bpf_prog *xdp_prog; struct" + " list_head ptype_specific; int " + " ifindex; unsigned int real_num_rx_queues; struct" + " netdev_rx_queue *_rx; unsigned int gro_max_size;" + " unsigned int gro_ipv4_max_size; rx_handler_func_t= " + " *rx_handler; void *rx_handler_data; possible_n= et_t" + " nd_net; #ifdef CONFIG_NETPOLL; struct" + " netpoll_info *npinfo; #endif; #ifdef CONFIG_NET_XGRES= S;" + " struct bpf_mprog_entry *tcx_ingress; #endif; char = " + " name[IFNAMSIZ]; struct netdev_name_node *name_node; str= uct" + " dev_ifalias *ifalias;unsigned long mem_end; unsig= ned" + " long mem_start; unsigned long " + " base_addr;struct list_head dev_list; struct list_head= " + " napi_list; struct list_head unreg_list; struct" + " list_head close_list; struct list_head ptype_a= ll;" + " struct { struct list_head upper; struct list_head lower; }" + " adj_list;xdp_features_t xdp_features; const struct" + " xdp_metadata_ops *xdp_metadata_ops; const struct" + " xsk_tx_metadata_ops *xsk_tx_metadata_ops; unsigned short = " + " gflags; unsigned short needed_tailroom;" + " netdev_features_t hw_features; netdev_features_t " + " wanted_features; netdev_features_t vlan_features;" + " netdev_features_t hw_enc_features; netdev_features_t = " + " mpls_features; unsigned int min_mtu; unsigned int= " + " max_mtu; unsigned short type; unsigned char = " + " min_header_len; unsigned char name_assign_typ= e;" + " int group; struct net_device_stats" + " stats;struct net_device_core_stats __percpu *core_stats;atom= ic_t" + " tx_request;" + ) + self._check_matches(line, 1) + + def test_struct_group_06(self): + """struct_group(addrs).""" + line =3D ( + "struct_group(addrs, unsigned char h_dest[ETH_ALEN]; unsigne= d" + " char h_source[ETH_ALEN]; ); __be16 h_vlan_proto;" + " __be16 h_vlan_TCI; __be16 " + " h_vlan_encapsulated_proto;" + ) + self._check_matches(line, 1) + + def test_struct_group_07(self): + """one struct_group(headers).""" + line =3D ( + "union { struct {struct sk_buff *next; struct sk_buff= " + " *prev; union { struct net_device *dev;unsigned lo= ng " + " dev_scratch; }; }; struct rb_node rbnode;st= ruct" + " list_head list; struct llist_node ll_node; };" + " struct sock *sk; union { ktime_t tstamp;= u64" + " skb_mstamp_ns;};char cb[48] ;" + " union { struct { unsigned long _skb_refdst; void = " + " (*destructor)(struct sk_buff *skb); }; struct list_head = " + " tcp_tsorted_anchor; #ifdef CONFIG_NET_SOCK_MSG; unsigned lon= g " + " _sk_redir; #endif; }; #if defined(CONFIG_NF_CONNTRACK= ) ||" + " defined(CONFIG_NF_CONNTRACK_MODULE); unsigned long = " + " _nfct; #endif; unsigned int len, data_len; __u16 = " + " mac_len, hdr_len;__u16 " + " queue_mapping;#ifdef __BIG_ENDIAN_BITFIELD; #define CLONED_M= ASK " + " (1 << 7); #else; #define CLONED_MASK 1; #endif; #defi= ne" + " CLONED_OFFSET offsetof(struct sk_buff," + " __cloned_offset); __u8 cloned:1, nohdr:1= ," + " fclone:2, peeked:1, head_frag:1, pfmemalloc:1," + " pp_recycle:1;#ifdef CONFIG_SKB_EXTENSIONS; __u8 = " + " active_extensions; #endif;struct_group(headers, __u8 = " + " pkt_type:3;__u8 ignore_df:1; __= u8 " + " dst_pending_confirm:1; __u8 = " + " ip_summed:2; __u8 ooo_okay:1; __u8 = " + " tstamp_type:2;#ifdef CONFIG_NET_XGRESS; __u8 = " + " tc_at_ingress:1;__u8 " + " tc_skip_classify:1; #endif; __u8 " + " remcsum_offload:1; __u8 csum_complete_sw:= 1;" + " __u8 csum_level:2; __u8 = " + " inner_protocol_type:1; __u8 l4_hash:1; __= u8 " + " sw_hash:1; #ifdef CONFIG_WIRELESS; __u8 = " + " wifi_acked_valid:1; __u8 " + " wifi_acked:1; #endif; __u8 no_fcs:1;__u8 = " + " encapsulation:1; __u8 " + " encap_hdr_csum:1; __u8 csum_valid:1; #ifd= ef" + " CONFIG_IPV6_NDISC_NODETYPE; __u8 " + " ndisc_nodetype:2; #endif; #if IS_ENABLED(CONFIG_IP_VS); __u8= " + " ipvs_property:1; #endif; #if" + " IS_ENABLED(CONFIG_NETFILTER_XT_TARGET_TRACE) ||" + " IS_ENABLED(CONFIG_NF_TABLES); __u8 " + " nf_trace:1; #endif; #ifdef CONFIG_NET_SWITCHDEV; __u8 = " + " offload_fwd_mark:1; __u8 " + " offload_l3_fwd_mark:1; #endif; __u8 " + " redirected:1; #ifdef CONFIG_NET_REDIRECT; __u8 = " + " from_ingress:1; #endif; #ifdef CONFIG_NETFILTER_SKIP_EGRESS= ;" + " __u8 nf_skip_egress:1; #endif; #ifdef" + " CONFIG_SKB_DECRYPTED; __u8 decrypted:1;" + " #endif; __u8 slow_gro:1; #if" + " IS_ENABLED(CONFIG_IP_SCTP); __u8 " + " csum_not_inet:1; #endif; __u8 unreadable:= 1;" + " #if defined(CONFIG_NET_SCHED) || defined(CONFIG_NET_XGRESS);" + " __u16 tc_index;#endif; u16 = " + " alloc_cpu; union { __wsum csum; struct { __u16 " + " csum_start; __u16 csum_offset; }; }; __u32 = " + " priority; int skb_iif; __u32 = " + " hash; union { u32 vlan_all; struct { __be16 " + " vlan_proto; __u16 vlan_tci; }; }; #if" + " defined(CONFIG_NET_RX_BUSY_POLL) || defined(CONFIG_XPS); uni= on {" + " unsigned int napi_id; unsigned int sender_cpu; }; };" + " #ifdef CONFIG_NETWORK_SECMARK; __u32 secmark; #end= if;" + " union { __u32 mark; __u32 reserved_tailr= oom;" + " }; union { __be16 inner_protocol; __u8 " + " inner_ipproto; }; __u16 " + " inner_transport_header; __u16 " + " inner_network_header; __u16 inner_mac_head= er;" + " __be16 protocol; __u16 " + " transport_header; __u16 network_header; __= u16 " + " mac_header; #ifdef CONFIG_KCOV; u64 = " + " kcov_handle; #endif; );sk_buff_data_t tail;" + " sk_buff_data_t end; unsigned char *head," + " *data; unsigned int truesize; refcount_t = " + " users; #ifdef CONFIG_SKB_EXTENSIONS;struct skb_ext " + " *extensions; #endif;" + ) + self._check_matches(line, 1) + + def test_struct_group_08(self): + """two struct_group(stats).""" + line =3D ( + "enum ethtool_mac_stats_src src; struct_group(stats, u64" + " tx_pause_frames; u64 rx_pause_frames; ); enum" + " ethtool_mac_stats_src src; struct_group(stats, u64" + " undersize_pkts; u64 oversize_pkts; u64 fragments; u64 jabber= s;" + " u64 hist[ETHTOOL_RMON_HIST_MAX]; u64" + " hist_tx[ETHTOOL_RMON_HIST_MAX]; );" + ) + self._check_matches(line, 2) + + def test_struct_group_09(self): + """struct_group(tx_stats).""" + line =3D ( + "struct_group(tx_stats, u64 pkts; u64 onestep_pkts_unconfirmed= ;" + " u64 lost; u64 err; );" + ) + self._check_matches(line, 1) + + def test_struct_group_10(self): + """struct_group(zeroed_on_hw_restart) with a nested struct.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, u16 fw_id; struct { u8" + " allocated:1; u8 stop_full:1; } status; ); struct list_head l= ist;" + " atomic_t tx_request;" + ) + self._check_matches(line, 1) + + def test_struct_group_11(self): + """struct_group(zeroed_on_hw_restart) with many fields.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, unsigned int status; u32" + " uid_status[IWL_MAX_UMAC_SCANS]; u64 start_tsf; bool" + " last_ebs_failed; enum iwl_mld_pass_all_sched_results_states" + " pass_all_sched_res; u8 fw_link_id; struct { u32" + " last_stats_ts_usec; enum iwl_mld_traffic_load status; }" + " traffic_load; );size_t cmd_size; void *cmd; unsigned long" + " last_6ghz_passive_jiffies; unsigned long" + " last_start_time_jiffies; u64 last_mlo_scan_time;" + ) + self._check_matches(line, 1) + + def test_struct_group_12(self): + """struct_group(zeroed_on_hw_restart) with a huge struct.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, struct ieee80211_bss_conf " + " *fw_id_to_bss_conf[IWL_FW_MAX_LINK_ID + 1]; struct ieee80211= _vif" + " *fw_id_to_vif[NUM_MAC_INDEX_DRIVER]; struct ieee80211_txq " + " *fw_id_to_txq[IWL_MAX_TVQM_QUEUES]; u8 used_phy_ids:" + " NUM_PHY_CTX; u8 num_igtks; struct { bool on; u32 ampdu_ref; = bool" + " ampdu_toggle; u8 p80; struct { struct" + " iwl_rx_phy_air_sniffer_ntfy data; u8 valid:1, used:1; } phy;" + " #ifdef CONFIG_IWLWIFI_DEBUGFS; __le16 cur_aid; u8" + " cur_bssid[ETH_ALEN]; bool ptp_time; #endif; } monitor; #ifde= f" + " CONFIG_PM_SLEEP; bool netdetect; #endif; struct ieee80211_vi= f" + " *p2p_device_vif; bool bt_is_active; struct ieee80211_vif" + " *nan_device_vif; ); struct ieee80211_link_sta " + " *fw_id_to_link_sta[IWL_STATION_COUNT_MAX];struct device *dev= ;" + " struct iwl_trans *trans; const struct iwl_rf_cfg *cfg; const" + " struct iwl_fw *fw; struct ieee80211_hw *hw; struct wiphy *wi= phy;" + " struct wiphy_iftype_ext_capab" + " ext_capab[IWL_MLD_EXT_CAPA_NUM_IFTYPES]; u8" + " sta_ext_capab[IWL_MLD_STA_EXT_CAPA_SIZE]; struct iwl_nvm_dat= a" + " *nvm_data; struct iwl_fw_runtime fwrt; struct dentry" + " *debugfs_dir; struct iwl_notif_wait_data notif_wait; struct" + " list_head async_handlers_list; spinlock_t async_handlers_loc= k;" + " struct wiphy_work async_handlers_wk; struct wiphy_delayed_wo= rk" + " ct_kill_exit_wk; struct { u32 running:1, do_not_dump_once:1," + " #ifdef CONFIG_PM_SLEEP; in_d3:1, resuming:1, #endif;" + " in_hw_restart:1; } fw_status; struct { u32 hw:1, ct:1; }" + " radio_kill; u32 power_budget_mw; struct mac_address" + " addresses[IWL_MLD_MAX_ADDRESSES]; struct iwl_mld_scan scan;" + " struct iwl_mld_survey *channel_survey; #ifdef CONFIG_PM_SLEE= P;" + " struct wiphy_wowlan_support wowlan; u32 debug_max_sleep; #en= dif;" + " #ifdef CONFIG_IWLWIFI_LEDS; struct led_classdev led; #endif;" + " enum iwl_mcc_source mcc_src; bool bios_enable_puncturing; st= ruct" + " iwl_mld_baid_data *fw_id_to_ba[IWL_MAX_BAID]; u8" + " num_rx_ba_sessions; struct iwl_mld_rx_queues_sync rxq_sync;" + " struct list_head txqs_to_add; struct wiphy_work add_txqs_wk;" + " spinlock_t add_txqs_lock; u8 *error_recovery_buf; struct" + " iwl_mcast_filter_cmd *mcast_filter_cmd; u8 mgmt_tx_ant; u8" + " set_tx_ant; u8 set_rx_ant; bool fw_rates_ver_3; struct" + " iwl_mld_low_latency low_latency; bool ibss_manager; #ifdef" + " CONFIG_THERMAL; struct thermal_zone_device *tzone; struct" + " iwl_mld_cooling_device cooling_dev; #endif; struct ptp_data" + " ptp_data; struct iwl_mld_time_sync_data *time_sync; struct" + " ftm_initiator_data ftm_initiator;" + ) + self._check_matches(line, 1) + + def test_struct_group_13(self): + """struct_group(zeroed_on_not_authorized).""" + line =3D ( + "struct_group(zeroed_on_not_authorized, u8 primary; u8" + " selected_primary; u16 selected_links; enum iwl_mld_emlsr_blo= cked" + " blocked_reasons; enum iwl_mld_emlsr_exit last_exit_reason;" + " unsigned long last_exit_ts; u8 exit_repeat_count; unsigned l= ong" + " last_entry_ts; ); struct wiphy_work unblock_tpt_wk; struct" + " wiphy_delayed_work check_tpt_wk; struct wiphy_delayed_work" + " prevent_done_wk; struct wiphy_delayed_work tmp_non_bss_done_= wk;" + ) + self._check_matches(line, 1) + + def test_struct_group_14(self): + """struct_group(zeroed_on_hw_restart) with nested struct.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, u8 fw_id; struct" + " iwl_mld_session_protect session_protect; struct ieee80211_st= a" + " *ap_sta; bool authorized; u8 num_associated_stas; bool" + " ap_ibss_active; enum iwl_mld_cca_40mhz_wa_status" + " cca_40mhz_workaround; #ifdef CONFIG_IWLWIFI_DEBUGFS; bool" + " beacon_inject_active; #endif; u8 low_latency_causes; bool" + " ps_disabled; time64_t last_link_activation_time; );struct" + " iwl_mld *mld; struct iwl_mld_link deflink; struct iwl_mld_li= nk " + " *link[IEEE80211_MLD_MAX_NUM_LINKS]; struct iwl_mld_emlsr eml= sr;" + " #ifdef CONFIG_PM_SLEEP; struct iwl_mld_wowlan_data wowlan_da= ta;" + " #endif; #ifdef CONFIG_IWLWIFI_DEBUGFS; bool use_ps_poll; boo= l" + " disable_bf; struct dentry *dbgfs_slink; #endif; enum" + " iwl_roc_activity roc_activity; struct iwl_mld_int_sta aux_st= a;" + " struct wiphy_delayed_work mlo_scan_start_wk;" + ) + self._check_matches(line, 1) + + def test_struct_group_15(self): + """struct_group(zeroed_on_hw_restart) with small struct.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, u32 last_rate_n_flags; boo= l" + " in_fw; s8 signal_avg; );struct rcu_head rcu_head; u32 fw_id;" + ) + self._check_matches(line, 1) + + def test_struct_group_16(self): + """struct_group(zeroed_on_hw_restart) with many enums.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, enum ieee80211_sta_state" + " sta_state; enum iwl_fw_sta_type sta_type; );struct iwl_mld *= mld;" + " struct ieee80211_vif *vif; struct iwl_mld_rxq_dup_data" + " *dup_data; u8 tid_to_baid[IWL_MAX_TID_COUNT]; u8 data_tx_ant= ;" + " struct iwl_mld_link_sta deflink; struct iwl_mld_link_sta " + " *link[IEEE80211_MLD_MAX_NUM_LINKS]; struct iwl_mld_ptk_pn " + " *ptk_pn[IWL_NUM_DEFAULT_KEYS]; struct iwl_mld_per_q_mpdu_cou= nter" + " *mpdu_counters;" + ) + self._check_matches(line, 1) + + def test_struct_group_17(self): + """struct_group(zeroed_on_hw_restart) with channel data.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, u8 fw_id; struct" + " cfg80211_chan_def chandef; );u32 channel_load_by_us; u32" + " avg_channel_load_not_by_us; struct iwl_mld *mld;" + ) + self._check_matches(line, 1) + + def test_struct_group_18(self): + """mixture of struct_group and struct rcu_head.""" + line =3D ( + "struct rcu_head rcu_head;struct_group(zeroed_on_hw_restart, u= 8" + " fw_id; bool active; struct ieee80211_tx_queue_params" + " queue_params[IEEE80211_NUM_ACS]; struct ieee80211_chanctx_co= nf " + " *chan_ctx; bool he_ru_2mhz_block; struct ieee80211_key_conf" + " *igtk; struct ieee80211_key_conf *bigtks[2]; );struct" + " iwl_mld_int_sta bcast_sta; struct iwl_mld_int_sta mcast_sta;" + " struct iwl_mld_int_sta mon_sta;struct ieee80211_key_conf" + " *ap_early_keys[6]; u32 average_beacon_energy; bool" + " silent_deactivation; struct iwl_probe_resp_data " + " *probe_resp_data;" + ) + self._check_matches(line, 1) + + def test_struct_group_19(self): + """x(ice_health_tx_hang_buf).""" + line =3D ( + "struct devlink_health_reporter *fw; struct" + " devlink_health_reporter *mdd; struct devlink_health_reporter" + " *port; struct devlink_health_reporter *tx_hang;" + " struct_group_tagged(ice_health_tx_hang_buf, tx_hang_buf, str= uct" + " ice_tx_ring *tx_ring; u32 head; u32 intr; u16 vsi_num; ); st= ruct" + " ice_aqc_health_status_elem fw_status; struct" + " ice_aqc_health_status_elem port_status;" + ) + self._check_matches(line, 1) + + def test_struct_group_sub(self): + """Replace struct_group body with a placeholder.""" + line =3D "foo bar struct_group(my, a(b{c}), d); qux;" + + result =3D NestedMatch(r"\bstruct_group\(").sub("REPLACED", line) + expected =3D "foo bar REPLACED qux;" + + self.assertEqual(result, expected) + + +class TestSubMacros(unittest.TestCase): + """ + Test macros that will be dropped. + """ + + def test_acquires_simple(self): + """Simple replacement test with __acquires""" + line =3D "__acquires(ctx) foo();" + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + + self.assertNotIn("__acquires(", result) + self.assertIn("foo();", result) + + def test_acquires_multiple(self): + """Multiple __acquires""" + line =3D "__acquires(ctx) __acquires(other) bar();" + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + + self.assertNotIn("__acquires(", result) + self.assertEqual(result.count("REPLACED"), 2) + + def test_acquires_nested_paren(self): + """__acquires with nested pattern""" + line =3D "__acquires((ctx1, ctx2)) baz();" + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + + self.assertNotIn("__acquires(", result) + self.assertIn("baz();", result) + + def test_must_hold(self): + """__must_hold with a pointer""" + line =3D "__must_hold(&lock) do_something();" + result =3D NestedMatch(r"__must_hold\s*\(").sub("REPLACED", line) + + self.assertNotIn("__must_hold(", result) + self.assertIn("do_something();", result) + + def test_must_hold_shared(self): + """__must_hold with an upercase defined value""" + line =3D "__must_hold_shared(RCU) other();" + result =3D NestedMatch(r"__must_hold_shared\s*\(").sub("REPLACED",= line) + + self.assertNotIn("__must_hold_shared(", result) + self.assertIn("other();", result) + + def test_no_false_positive(self): + """ + Ensure that unrelated text containing similar patterns is preserved + """ + line =3D "call__acquires(foo); // should stay intact" + result =3D NestedMatch(r"\b__acquires\s*\(").sub("REPLACED", line) + + self.assertEqual(result, line) + + def test_mixed_macros(self): + """Add a mix of macros""" + line =3D "__acquires(ctx) __releases(ctx) __must_hold(&lock) foo()= ;" + + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + result =3D NestedMatch(r"__releases\s*\(").sub("REPLACED", result) + result =3D NestedMatch(r"__must_hold\s*\(").sub("REPLACED", result) + + self.assertNotIn("__acquires(", result) + self.assertNotIn("__releases(", result) + self.assertNotIn("__must_hold(", result) + + self.assertIn("foo();", result) + + def test_no_macro_remains(self): + """Ensures that unmatched macros are untouched""" + line =3D "do_something_else();" + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + + self.assertEqual(result, line) + + +class TestSubReplacement(unittest.TestCase): + """Test argument replacements""" + + @classmethod + def setUpClass(cls): + """Define a NestedMatch to be used for all tests""" + cls.matcher =3D NestedMatch(re.compile(r"__acquires\s*\(")) + + def test_sub_with_capture(self): + """Test all arguments replacement with a single arg""" + line =3D "__acquires(&ctx) foo();" + + result =3D self.matcher.sub(r"ACQUIRED(\0)", line) + + self.assertIn("ACQUIRED(&ctx)", result) + self.assertIn("foo();", result) + + def test_sub_zero_placeholder(self): + """Test all arguments replacement with a multiple args""" + line =3D "__acquires(arg1, arg2) bar();" + + result =3D self.matcher.sub(r"REPLACED(\0)", line) + + self.assertIn("bar();", result) + self.assertIn("REPLACED(arg1, arg2)", result) + + def test_sub_single_placeholder(self): + """Single replacement rule for \1""" + line =3D "__acquires(ctx) foo();" + result =3D self.matcher.sub(r"ACQUIRED(\1)", line) + + self.assertIn("foo();", result) + self.assertIn("ACQUIRED(ctx)", result) + + def test_sub_multiple_placeholders(self): + """Replacement rule for both \1 and \2""" + line =3D "__acquires(arg1, arg2) bar();" + result =3D self.matcher.sub(r"REPLACE(\1, \2)", line) + + self.assertIn("bar();", result) + self.assertIn("REPLACE(arg1, arg2)", result) + + def test_sub_mixed_placeholders(self): + """Replacement rule for \0, \1 and additional text""" + line =3D "__acquires(foo, bar) baz();" + result =3D self.matcher.sub(r"START(\0) END(\1)", line) + + self.assertIn("baz();", result) + self.assertIn("START(foo, bar) END(foo)", result) + + def test_sub_no_placeholder(self): + """Replacement without placeholders""" + line =3D "__acquires(arg) foo();" + result =3D self.matcher.sub(r"NO_BACKREFS()", line) + + self.assertIn("foo();", result) + self.assertIn("NO_BACKREFS()", result) + + def test_sub_count_parameter(self): + """Verify that the algorithm stops after the requested count""" + line =3D "__acquires(a1) x(); __acquires(a2) y();" + result =3D self.matcher.sub(r"ONLY_FIRST(\1)", line, count=3D1) + + self.assertIn("ONLY_FIRST(a1) x();", result) + self.assertIn("__acquires(a2) y();", result) + + +# ---------------------------------------------------------------------- +# Run all tests +# ---------------------------------------------------------------------- +if __name__ =3D=3D "__main__": + run_unittest(__file__) --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 7242937C0ED; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=euS9IwqTxSJax6XTk9rYeQSd2k0PhIveW57FvqoE7SlNTw06VKwMf0LTlpr79AnbOxiuRy1Ik2K+lnC9mE3SI8kUCNRhtRL/pvgrNuyYSvEiMaghLEsxZCjMQ7iPFPrRz5OVLbGQHJyKA6dsubrBlP1udXcdcvdC/PELDABAA8Q= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=Vgz8udadx0cwepC/wsp/hEk+Bl4FBDA/00MijiNSly0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=UF2e9rAURE+p3aG990zp6umjPzEYZmdUAkrTrYHslURXknu+NNe2RlDjv1CbBMzmyD3ZJBBeeZ8OjWh5lKyjkVVeEfmJAg+KVklZopZQ74N9U9p1ZdrmoYq4iXyxKdP8S7tDiWy+muufXmxODOahIVSbUtCHNZnXy5XFux5hz9o= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=YP5vGpOv; 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="YP5vGpOv" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 13200C4AF49; Thu, 29 Jan 2026 08:08:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=Vgz8udadx0cwepC/wsp/hEk+Bl4FBDA/00MijiNSly0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YP5vGpOvHl24KZtFS2lZlEeeb735cIH0uq+vhbQZ2e7nKwUMN5fw8MAbs58UlPVKx 0OROfZZnNcewLqsK0HIRLgknHMJo+WOm8ep+be5EwzprkiWi1U21lj1/TENDurv1mO hbBGtiSFoLATC46u+uN3kmp7/upOE/QUzw3A5n97dydFPnJUK0RCgbbIG6+2uTQadd MkdzE1zaHdozS7OZjrdjc+M2HwE56Ye/yF+9gORYZuYc0iNkTLJl8WeVi43TnDAvH5 kZohuBMT3uwl9x5mbb3hllsIHbiTR8L1erlxNcrvN+O6+0GEypaLvVUts+WV1MtM1s Q+FNWlqjKz7mA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERO1-1Ggj; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 23/30] docs: kdoc_parser: better handle struct_group macros Date: Thu, 29 Jan 2026 09:08:14 +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 converting them on two steps, implement a single logic to parse them using the new sub functionality of NestedMatch.sub(). Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 10 +++++----- 1 file 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 3a5614106af7..d2eb93f9d489 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -124,10 +124,11 @@ struct_xforms =3D [ # 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('), + (NestedMatch(r'\bstruct_group\s*\('), r'\2'), + (NestedMatch(r'\bstruct_group_attr\s*\('), r'\3'), + (NestedMatch(r'\bstruct_group_tagged\s*\('), r'struct \1 { \3 } \2;'), + (NestedMatch(r'\b__struct_group\s*\('), r'\4'), + # # Replace macros # @@ -153,7 +154,6 @@ struct_xforms =3D [ (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]; }'), - (NestedMatch(r'\bSTRUCT_GROUP\('), r'\0'), ] =20 # --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 74D4037C0F1; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=u6jgVqeeCvwfGYnHtuHw73Swd1owHmwIBECta1BXvsIh9FeVznQIWep+X+PSBJReoHf28jEaoknVDy3PtRd3E2/1Qg5lKjlQNIc2CNqo5AZ94K9rPo1gNFeKWWh9z/5g/zuWXEK5XdP+rs0o/TzU+Lv/MFb797+AAlH4hv6DrnY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=jXKyTJKBXMc1s7NB0MjWyQ30waz0m2moRL2HWFXUGcQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=dBrkRFGrqQpg6Gtya8LRDlsBrSDmrIt4Se4p1CWFF3cGhD7tqzU94uw49mKNSNq5PjKpwg2lLtiO/wChJsEN67QGNR8PLA013IGoL0bUqDEa9CX7+KeYMijf0TLAj38ztRzmfSjBvyMm/AVOevJQPOJAcYrF5NhMPryeShxaeA0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=J7PkFnqw; 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="J7PkFnqw" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1810FC4AF0B; Thu, 29 Jan 2026 08:08:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=jXKyTJKBXMc1s7NB0MjWyQ30waz0m2moRL2HWFXUGcQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=J7PkFnqwl2NyEeDLu1PjLukhjjtiF+Ro2e05fbSOt0bbYe/La5snvMsV/XSZp0/kW 7tRFxouHgJdH9LNlXIjiRrXisPkCjbjbWU9X1TqnPD/6OWGeQnW+BE9DSIENFTYMF/ 4S4+ZvgncMp8Y9a3LrLSBQnR6jUE4VacgREmd58LhtEpvytSPSjgZrw9MvJVRAzHad bdu1aKJI4bLQ8C59UsWBAeaFD3L1LyrHoTj93SSsJE3mrYLitlkoBHoa4XSIJKmrm/ 6a0A8riOd4DXnNvl8SDpJ06A4ULLZT/BFl63zJyP1oHt86G3GO6DqRXRFLKKrrHh2a QuIqETItOATxQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERO5-1O5T; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 24/30] docs: kdoc_re: fix a parse bug on struct page_pool_params Date: Thu, 29 Jan 2026 09:08:15 +0100 Message-ID: <053367b7bf66f07444b45790db0e2b1998d3a3fe.1769673038.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 struct page_pool_params definition has a private definition on it: struct page_pool_params { struct_group_tagged(page_pool_params_fast, fast, unsigned int order; unsigned int pool_size; int nid; struct device *dev; struct napi_struct *napi; enum dma_data_direction dma_dir; unsigned int max_len; unsigned int offset; ); struct_group_tagged(page_pool_params_slow, slow, struct net_device *netdev; unsigned int queue_idx; unsigned int flags; /* private: used by test code only */ void (*init_callback)(netmem_ref netmem, void *arg); void *init_arg; ); }; This makes kernel-doc parser to miss the end parenthesis of the second struct_group_tagged, causing documentation issues. Address it by ensuring that, if are there anything at the stack, it will be placed as the last part of the argument. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_re.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 858cc688a58f..5f455ffff7b2 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -201,6 +201,9 @@ class NestedMatch: """ =20 stack =3D [] + start =3D 0 + offset =3D 0 + pos =3D 0 =20 for match_re in self.regex.finditer(line): start =3D match_re.start() @@ -250,6 +253,11 @@ class NestedMatch: yield start, offset, pos + 1 break =20 + # When /* private */ is used, it may end the end delimiterq + if stack: + stack.pop() + yield start, offset, len(line) + 1 + def search(self, line): """ This is similar to re.search: --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 82B9537C104; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=Pw8GpZIdyp5eMkso9cXhgOhPHA0Hk7OaHBpK0eA01gUSvW7a29fG33kXp+a8zn9IMUHq5R5uhTyLdJ/56ozR/d58u1ooiCnTYbXr65pgSzEnrSvojXvRFP/YaY10JgPCp4H15svuYpK+2nKo0U8C5BQb9RAnL+0daJrN1ZREjkU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=5IMb08zUAZZvfVWXPYkW/4qcvpNOxc4eEZSFARXvZuc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=frg14hcQBlAebLT0Udj6YitGakgBc+qeX10/fTrcGeRdMFjVGezgVCk017vck4q3l6su1x3gsJDe5Z5bLjnsbcAOt8CRUF6uqJf4JCMfZ6DTyIEDkxF8n6GuPM3CH71EqGUJrIgUGC5U1f7/jvhHGOVIqLvMY4GSkMfZu5b3Sh0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=OdQsPwCU; 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="OdQsPwCU" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2207DC2BC9E; Thu, 29 Jan 2026 08:08:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=5IMb08zUAZZvfVWXPYkW/4qcvpNOxc4eEZSFARXvZuc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=OdQsPwCU87ijJQAvR4bFQKGyfKuTiPXIrfP8nlxqb3ywYjSJv61k2ROvpdRebYQsQ ABZtUOiBDZCpHsKzaWLcBfp2ZXefQ+izcFxzYQ99yaj+nffM7X5FXlaGQVnAbK/CLp LmfjgelLDoPuEDMDekhHRjI6cipt3FcG1Wl3xHKoEJ2XI7mRm8ij5ewcMbHurgHpmS 0Pj2A7Lb+VIUKweKzqbb13O4Q68pi4Uvwjr+/shCizR50sNjLOybTe6OU+G+8DJejB 1dgaqR3yRPxd1r7i2FySvp2R2lxxpzqRa9h+nx8y3b9QCVM/dYVziKX6YVqt6lN/Gq ObnCqicRTDTqA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000ERO9-1VNv; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 25/30] docs: kdoc_re: add a helper class to declare C function matches Date: Thu, 29 Jan 2026 09:08:16 +0100 Message-ID: <9d3d27d956b25921cf40410e59a17a86caef32f6.1769673038.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 a more convenient class to match C functions and avoiding issues at the beginning and ending of NestedMatch inits. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 5f455ffff7b2..a49b42e3d189 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -380,3 +380,14 @@ class NestedMatch: """ =20 return f'NestedMatch("{self.regex.regex.pattern}")' + + +class CFunction(NestedMatch): + r""" + Variant of NestedMatch. + + It overrides the init method to ensure that the regular expression will + start with a ``\b`` and end with a C function delimiter (open parenthe= sis). + """ + def __init__(self, regex): + self.regex =3D KernRe(r"\b" + regex + r"\s*\(") --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 74E3837C0F2; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=uTTqEy8ob3UXH3Bqba3/XsxFhrRgfAev9XVomCJRKIhqjiimQ0+Xv/HsoXxyrIZCpmpX3lagsycv2p8XYVxlF0s0jV6fSZ1vdxrmUMVV/vNn7ux4ndj2XK86fktcDf/8zlsMw7CYDKQnngV7I6jpLpjONpuaGPaGbHcIwNJSr+k= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=HZIWPQtHuKRBHDG4lIuIJ9k4nhNjGP3jcqbI9/NYBFM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=j2nvXdTkWTG2kS9CeK+RZfOHWYpUhARvzwzASi1rD/xPERbLJgQfAURROynFDfyObg00FSTYtut6+bBCbdXfeXOkaZLTaZttbVVqMIkZSNwBc2AG6b/IB6Ftkq6PbGlETZ5Lupga0Eh51llD+J9/jy5L0lXvTfm++Iehmab5lhk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=GSjxV5N8; 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="GSjxV5N8" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 26799C2BCFC; Thu, 29 Jan 2026 08:08:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=HZIWPQtHuKRBHDG4lIuIJ9k4nhNjGP3jcqbI9/NYBFM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GSjxV5N8m6DyFxui8ZZdGu4+xPizuar3wU0AtGMsI1qMuSXRq0l1WC9X+Zm3hRWAb uHyt5mVPJxNtLtSoi/g5xBZ+XgycQK5IV5d3TCaY/cONDpBFpi5AZyMGEDMZSMAaS7 PvNQ9d8qwDoZkcH6vynHxk5dHtdrfMEC/byQCk12jutLU9F/f4tGSLoCiUvVb+ZNzT 3plvFnws7sQ+qDOtrTZrwPZvo0lOixx671zZ3a8i3gmYGclELOt1gfZs/iCquZRctV r9AB9hYU9TzKNAtgXBplJu0RrpHkoOish+Q/YVMq167JVSHF23onkBcndBpuq5xnaA thMRLBM+FNnVg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000EROD-1cdk; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 26/30] docs: kdoc_parser: use the new CFunction class Date: Thu, 29 Jan 2026 09:08:17 +0100 Message-ID: <4ca4e256922bc42ce1c86e70c20e6a35a599fcfd.1769673038.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 match logic for transforms becomes a lot clearer if we use CFunction convenient alias class instead of NestedMatch. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 38 ++++++++++++++-------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index d2eb93f9d489..50d57c6799bb 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -13,7 +13,7 @@ import sys import re from pprint import pformat =20 -from kdoc.kdoc_re import NestedMatch, KernRe +from kdoc.kdoc_re import CFunction, KernRe from kdoc.kdoc_item import KdocItem =20 # @@ -119,22 +119,22 @@ struct_xforms =3D [ # # As it doesn't properly match the end parenthesis on some cases. # - # So, a better solution was crafted: there's now a NestedMatch + # So, a better solution was crafted: there's now a CFunction # class that ensures that delimiters after a search are properly # matched. So, the implementation to drop STRUCT_GROUP() will be # handled in separate. # - (NestedMatch(r'\bstruct_group\s*\('), r'\2'), - (NestedMatch(r'\bstruct_group_attr\s*\('), r'\3'), - (NestedMatch(r'\bstruct_group_tagged\s*\('), r'struct \1 { \3 } \2;'), - (NestedMatch(r'\b__struct_group\s*\('), r'\4'), + (CFunction('struct_group'), r'\2'), + (CFunction('struct_group_attr'), r'\3'), + (CFunction('struct_group_tagged'), r'struct \1 { \3 } \2;'), + (CFunction('__struct_group'), r'\4'), =20 # # Replace macros # - # TODO: use NestedMatch for FOO($1, $2, ...) matches + # TODO: use CFunction on all FOO($1, $2, ...) matches # - # it is better to also move those to the NestedMatch logic, + # it is better to also move those to the CFunction logic, # to ensure that parentheses will be properly matched. # (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re.S), @@ -185,17 +185,17 @@ function_xforms =3D [ (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__ +"), ""), - (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"__attribute__\s*\("), ""), + (CFunction("__cond_acquires"), ""), + (CFunction("__cond_releases"), ""), + (CFunction("__acquires"), ""), + (CFunction("__releases"), ""), + (CFunction("__must_hold"), ""), + (CFunction("__must_not_hold"), ""), + (CFunction("__must_hold_shared"), ""), + (CFunction("__cond_acquires_shared"), ""), + (CFunction("__acquires_shared"), ""), + (CFunction("__releases_shared"), ""), + (CFunction("__attribute__"), ""), ] =20 # --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 8525537C105; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=sQGDUrcR4Cfq9oYfe8RDvtqjRat/IqKTXj0WDLf+UhGUQr3gkRj814rHtDfmczsYvjDjEOr9jYj3Kznely1g581hbDb24Z726winwadgDUmpeowM5qSCpQm5gwrR8g+MsoUCCrw2I4P89kK/uwAGmmyrU07Pflu0aWLspQ1FJqA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=aAYr/rdf8rPhk+DzwcPpBGhnCkODn024mb+J5zDgPZA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=tcacPTVsdrDSLe0lZKA0ISnQuTxnRI7PJ7ngTechVgjUa09WqE9NepeDydISynU6k8np2ewizL/KiGUzPuOCcZ5MRNy/KwR5lYMxsmm9Uvb2WLyf29maS8ey3Az2P2cqIPdIdECGTlJziFgzmCNxT62jHt0QpE+kpF0dQk4SOWA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=HxEvSNHQ; 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="HxEvSNHQ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2C2EAC2BCB6; Thu, 29 Jan 2026 08:08:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=aAYr/rdf8rPhk+DzwcPpBGhnCkODn024mb+J5zDgPZA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=HxEvSNHQEtL0D59ODsnQi0p3l8kMpRAIJaWt8HUV5lvtVPe2caGw5Z0eLuIIQN8Cr 4xRaxDBGT+igKQhlHOaxNvX+eFQ6ZA82YxsTv0FjkNdeBvTBYl+iYm50wea3VTsOcQ fKt6u+LN7F4u4p4Zx30THYRuTvRzoAHmjiH9PlcAVFT47GW9CKIqfpogm1q0jwt9b3 7RjMh3jWaL0T1izR+e8ryofdpsfSH4aWF1PVlipelfiqJLjpGEWRmXNp90sSw+dIzh /5erIn2XU+qhq6rfbrfcgR33uPNecU9q3U2RZybpjFOVd8oICaZfNpY9xMZj77zvIS xM/EStNmmUzQA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000EROH-1jpG; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Alexander Lobakin , Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 27/30] docs: kdoc_parser: minimize differences with struct_group_tagged Date: Thu, 29 Jan 2026 09:08:18 +0100 Message-ID: <50ef80ed8a1a638d08974e55a7828371bab09c0d.1769673038.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 While the previous version does a better job representing the actual struct, it ends losing documentation from each member. Change the replacements to minimize such changes. With that, the only differences before/after using NestedMatch new replacement logic are (at man page output): --- before.log 2026-01-29 06:14:20.163592584 +0100 +++ after.log 2026-01-29 06:32:04.811370234 +0100 @@ -1573701 +1573701 @@ -.BI " struct ice_health_tx_hang_buf tx_hang_buf;" +.BI " struct ice_health_tx_hang_buf tx_hang_buf;" @@ -4156451 +4156451 @@ -.BI " struct libeth_fq_fp fp;" +.BI " struct libeth_fq_fp fp;" @@ -4164041 +4164041 @@ -.BI " struct libeth_xskfq_fp fp;" +.BI " struct libeth_xskfq_fp fp;" @@ -4269434 +4269434 @@ -.BI " struct page_pool_params_fast fast;" +.BI " struct page_pool_params_fast fast;" @@ -4269452 +4269452 @@ -.BI " struct page_pool_params_slow slow;" +.BI " struct page_pool_params_slow slow;" @@ -4269454 +4269454 @@ -.BI " STRUCT_GROUP( struct net_device *netdev;" +.BI " struct net_device *netdev;" e.g. basically whitespaces, plus a fix NestedMatch to better handle /* private */ comments. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 50d57c6799bb..1e8e156e2a9e 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -126,7 +126,7 @@ struct_xforms =3D [ # (CFunction('struct_group'), r'\2'), (CFunction('struct_group_attr'), r'\3'), - (CFunction('struct_group_tagged'), r'struct \1 { \3 } \2;'), + (CFunction('struct_group_tagged'), r'struct \1 \2; \3'), (CFunction('__struct_group'), r'\4'), =20 # --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 A941737D106; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=GC5wduQsc1zvDCqKBm7izf4lVBh+eQ9EggXLfgLTNQdrWmTpkfbhmb9tdnEahpccISQ4lOscq85lEOAP5Hcj9oCSmu/BUWCQ+raKyqNuJtc5J+kvEFEh/LiOrW3qO00IYI/VE1gu2ekFTxEfph34kgaibuoEhUtJmwEbbPa9CAQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=F7SXVJQaKXSGTPt0S8ELbYxmxnPghzSZdaEyiqG1MT0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=lSqy84bUjmAknRV6+mcfrcKypVqatXEs0StH34V5yTb0OEL+ImbTRc/QNbxc2142FNZVXdGHexrAnyb5OCg+YjkjOxhjjViqQyCZYdsWNR3+c2tAKUmacdmkTPMSKpHRRw9gpSzIIf0vyM0dz+yLGEStwOk+jhebt7Ux1GXys7A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=EsmRyLsP; 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="EsmRyLsP" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 36263C2BCB7; Thu, 29 Jan 2026 08:08:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=F7SXVJQaKXSGTPt0S8ELbYxmxnPghzSZdaEyiqG1MT0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=EsmRyLsPaYkZHy8GmfAeTZvYM9esvTbEqahXXySqKeSbpWkU/WGKuExYbie/U5Zhf TMDOoDcI33QRtygeIxOoiRXWNAcATKUqJf82ztjG1pe4iVVV8IAMP2/FHsub+f9zPa asImPEdlR1465VH6H05BBCpePoTWp2t0f11Fw49+lFZSndHFo8o5OaEF+89w4IewmM e+UuUYA4q2S2Uxzd1GKQuJoPwKCW0eaSo61P7miLIuXiZN+Tyn+b2pwWJMB/4KTrib tMXAMdkYnRC5vwIDyJzqIneqCdyUN2jWR20A6lp4cAdX3pRkmZbid6VSM1MZhUp4e3 PZAvOf1Zq0avg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000EROL-1rP6; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, "Gustavo A. R. Silva" , Kees Cook , Mauro Carvalho Chehab , Randy Dunlap , Shuah Khan Subject: [PATCH v3 28/30] docs: kdoc_parser: move transform lists to a separate file Date: Thu, 29 Jan 2026 09:08:19 +0100 Message-ID: <9f8228c20b8849c068e107bcbcb1f24e1cbd36bb.1769673038.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 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. While here, drop the now obsolete comment about the two-steps logic to handle struct_group macros. 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. 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 | 147 ++------------------------ tools/lib/python/kdoc/xforms_lists.py | 117 ++++++++++++++++++++ 4 files changed, 133 insertions(+), 142 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..7357c97a4b01 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 1e8e156e2a9e..a280fe581937 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -75,142 +75,6 @@ doc_begin_func =3D KernRe(str(doc_com) + # initial " = * ' # struct_args_pattern =3D r'([^,)]+)' =20 -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*__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), ' '), - (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 CFunction - # class that ensures that delimiters after a search are properly - # matched. So, the implementation to drop STRUCT_GROUP() will be - # handled in separate. - # - (CFunction('struct_group'), r'\2'), - (CFunction('struct_group_attr'), r'\3'), - (CFunction('struct_group_tagged'), r'struct \1 \2; \3'), - (CFunction('__struct_group'), r'\4'), - - # - # Replace macros - # - # TODO: use CFunction on all FOO($1, $2, ...) matches - # - # it is better to also move those to the CFunction 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]; }'), -] - -# -# 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"__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"__no_context_analysis\s*"), ""), - (KernRe(r"__attribute_const__ +"), ""), - (CFunction("__cond_acquires"), ""), - (CFunction("__cond_releases"), ""), - (CFunction("__acquires"), ""), - (CFunction("__releases"), ""), - (CFunction("__must_hold"), ""), - (CFunction("__must_not_hold"), ""), - (CFunction("__must_hold_shared"), ""), - (CFunction("__cond_acquires_shared"), ""), - (CFunction("__acquires_shared"), ""), - (CFunction("__releases_shared"), ""), - (CFunction("__attribute__"), ""), -] - -# -# Transforms for variable prototypes -# -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"(?:/\*.*\*/)"), ""), - (KernRe(r";$"), ""), -] =20 # # Ancillary functions @@ -394,11 +258,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 @@ -889,7 +754,7 @@ class KernelDoc: # Go through the list of members applying all of our transformatio= ns. # members =3D trim_private_members(members) - members =3D self.apply_transforms(struct_xforms, members) + members =3D self.apply_transforms(self.xforms.struct_xforms, membe= rs) =20 # # Deal with embedded struct and union members, and drop enums enti= rely. @@ -1011,8 +876,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.apply_transforms(self.xforms.var_xforms, proto) =20 proto =3D proto.rstrip() =20 @@ -1104,7 +968,8 @@ class KernelDoc: # # Apply the initial transformations. # - prototype =3D self.apply_transforms(function_xforms, prototype) + prototype =3D self.apply_transforms(self.xforms.function_xform= s, + 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..88968bafdb78 --- /dev/null +++ b/tools/lib/python/kdoc/xforms_lists.py @@ -0,0 +1,117 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright(c) 2026: Mauro Carvalho Chehab . + +import re + +from kdoc.kdoc_re import CFunction, 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*__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), ' '), + (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)\([^\)]+\);'), ''), + + (CFunction('struct_group'), r'\2'), + (CFunction('struct_group_attr'), r'\3'), + (CFunction('struct_group_tagged'), r'struct \1 \2; \3'), + (CFunction('__struct_group'), r'\4'), + + # + # Replace macros + # + # TODO: use CFunction on all FOO($1, $2, ...) matches + # + # it is better to also move those to the CFunction 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"__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"__no_context_analysis\s*"), ""), + (KernRe(r"__attribute_const__ +"), ""), + (CFunction("__cond_acquires"), ""), + (CFunction("__cond_releases"), ""), + (CFunction("__acquires"), ""), + (CFunction("__releases"), ""), + (CFunction("__must_hold"), ""), + (CFunction("__must_not_hold"), ""), + (CFunction("__must_hold_shared"), ""), + (CFunction("__cond_acquires_shared"), ""), + (CFunction("__acquires_shared"), ""), + (CFunction("__releases_shared"), ""), + (CFunction("__attribute__"), ""), + ] + + #: Transforms for variables + 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"(?:/\*.*\*/)"), ""), + (KernRe(r";$"), ""), + ] --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 806F937C0FD; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=JAK2idPzn32D/6EwW/eiyiu4rIZUyVho3ozNYeqNmg3FG7RVs2HlKa5vqa/kc+K7W+9Bka7AVhmZqr1YaUyO9+y4oQySacga8ZSB2/FLZrQrnopBx+3PCeMplIG0/BHYa4SimgXWleC0358IgWZBqab5gR1hR/h6JN2KjUURp0s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=MdLnPnAzndL1eoVvG2zTdachsuvtbjqkmlcLwIIe92E=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=kbPJKvECfUROLfgnyu52EHpEKc29UREfrtjBF7icMfXmYXGXecMfJXogiaZiSlMH+C8oaNfV9SiC2gQ03v9+8IAdk52AySJo0Ey+E8sqs4wmu8ZABKg5yCGUetibKPdvt4h1WDRzXChRkWP4cdWSe6XNK0J2ytQ8+4t6qToTJC4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=LD+KnSar; 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="LD+KnSar" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 36553C2BCFF; Thu, 29 Jan 2026 08:08:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=MdLnPnAzndL1eoVvG2zTdachsuvtbjqkmlcLwIIe92E=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=LD+KnSarsgjUhWoM2nMKrChjT+5gIulUR3mkQ7lI39aVsY4N/pQySzOSxIXQ7TAQ5 A9lJpMb+lzu6Obf1eLxQ5sk0mycH2wnJrzMK6UdkiImSHsz2zrPjg9hhoLKGjR27JH Rb8ai7TN2cdj6peYDGZ4hrcrM0bsT1cuynakk/Li4nIzu/aPsisM+9dqKG+BQoLMBD HBozlddnNnUk8/0u8mt2mCAHoOBzM5eBGC1X9uYgzGX1Nx4KZTCbQPL0XUGHDGTeTR fiIyLrCNlonE57axpkc5BenEBcHIb/JV3ZHaaAa4xqL3Zk8bqT3K6lmHBD1BgrZwgE cah5pqypKCMCQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000EROP-1yGx; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 29/30] docs: kdoc_re: don't remove the trailing ";" with NestedMatch Date: Thu, 29 Jan 2026 09:08:20 +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 Removing it causes the parse to break some conversions, when NestedMatch is used on macros like __attribute__(). Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index a49b42e3d189..294051dbc050 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -358,10 +358,6 @@ class NestedMatch: =20 out +=3D new_sub =20 - # Drop end ';' if any - if pos < len(line) and line[pos] =3D=3D ';': - pos +=3D 1 - cur_pos =3D pos n +=3D 1 =20 --=20 2.52.0 From nobody Sat Feb 7 15:09:57 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 77CA437C0F6; Thu, 29 Jan 2026 08:08:31 +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=1769674111; cv=none; b=ArtXMIcKOuPbvkrH3Hys2N9Wl8rXj3eZTMziwhfq0ZUERFfOBY0Tz9bm/Wi2EkzOhDRPXMKDbkXN2xib20cckVD19Urwlb4AsMJ+3lYForP8S6gHLy3d16zMFT6myFAmcU+OINhYD5YC4PciCGMP1f8AY7HnvFSu5Pjr08y/dP8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769674111; c=relaxed/simple; bh=zrn1R99JmhSDpw80vFG4cNPSq/xnegn/WMP5J1mznhQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=XCDURU2mhzsgMAECovZjpwrotwFzjH5hWfc7EUIiXtrgI8NaJ3lJ1ODj/MPH0jRevjh8uVRuTwwhFXswuBWHe2ZEog0lEMHmWGH2XyDMA9H/pHXKFdjk+mGtn+VvLNbGk8MzVuhg2aAFlEX6l3gIUtTUPZNP6inMRv9rHhnJnmk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=uhVQE0cl; 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="uhVQE0cl" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3A3C2C2BD04; Thu, 29 Jan 2026 08:08:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769674111; bh=zrn1R99JmhSDpw80vFG4cNPSq/xnegn/WMP5J1mznhQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uhVQE0clrmRRFi6sGV6bb+5Ub4LO1z8yNb9HI/vnrJW+Jp3s1Br8Ym/rNoefncoiC nA/7J5lgEJMtAXkHq6CY/wh84UMpacfDQkvPayr4v4Er5buS5c+Vm8psLK21oXkf6A BaJnF4xeffly1o7j0tzxhLJLrA6B5FRmk95Wjf0/eZ35OGyx6juJ1Bdkl1pVWkgZ1D yljMKKDrrJM3H4UHjz5mvwyNNGAUJ5MWu6WwwtgzhCVRr50bigYZmwY5yF7qanLyBP pdX8AHr2XMznKUKthYQgDBRLSb0pETFbZPskImF6+HcUYgHYDI1dKqc2KcAI70hDly SxomQMtuh381g== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vlN4n-0000000EROT-25XE; Thu, 29 Jan 2026 09:08:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Kees Cook , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, "Gustavo A. R. Silva" , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v3 30/30] docs: xforms_lists.py: use CFuntion to handle all function macros Date: Thu, 29 Jan 2026 09:08:21 +0100 Message-ID: <823756f6f8e5864817464560227820d8ef3a600f.1769673038.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 new CFunction class handles better macros, as it works the same way C compilers do, handling delimiters tha right way. This allows removing complex regular expressions, placing instead just a simple one with the name(s) of the functions to be replaced. Doing a before/after check using "kernel-doc -man ." shows only cosmetic changes (whitespaces, mostly). Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/xforms_lists.py | 54 +++++++++++---------------- 1 file changed, 21 insertions(+), 33 deletions(-) diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/= xforms_lists.py index 88968bafdb78..6e917beceb89 100644 --- a/tools/lib/python/kdoc/xforms_lists.py +++ b/tools/lib/python/kdoc/xforms_lists.py @@ -17,51 +17,38 @@ class CTransforms: =20 #: 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*__guarded_by\s*\([^\)]*\)', re.S), ' '), - (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ' '), + (CFunction("__attribute__"), ' '), + (CFunction('__aligned'), ' '), + (CFunction('__counted_by'), ' '), + (CFunction('__counted_by_(le|be)'), ' '), + (CFunction('__guarded_by'), ' '), + (CFunction('__pt_guarded_by'), ' '), + (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)\([^\)]+\);'), ''), + + (CFunction('__cacheline_group_(begin|end)'), ''), =20 (CFunction('struct_group'), r'\2'), (CFunction('struct_group_attr'), r'\3'), (CFunction('struct_group_tagged'), r'struct \1 \2; \3'), (CFunction('__struct_group'), r'\4'), =20 - # - # Replace macros - # - # TODO: use CFunction on all FOO($1, $2, ...) matches - # - # it is better to also move those to the CFunction 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]; }'), + (CFunction('__ETHTOOL_DECLARE_LINK_MODE_MASK'), r'DECLARE_BITMAP(\= 1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), + (CFunction('DECLARE_PHY_INTERFACE_MASK',), r'DECLARE_BITMAP(\1, PH= Y_INTERFACE_MODE_MAX)'), + (CFunction('DECLARE_BITMAP'), r'unsigned long \1[BITS_TO_LONGS(\2)= ]'), + + (CFunction('DECLARE_HASHTABLE'), r'unsigned long \1[1 << ((\2) - 1= )]'), + (CFunction('DECLARE_KFIFO'), r'\2 *\1'), + (CFunction('DECLARE_KFIFO_PTR'), r'\2 *\1'), + (CFunction('(?:__)?DECLARE_FLEX_ARRAY'), r'\1 \2[]'), + (CFunction('DEFINE_DMA_UNMAP_ADDR'), r'dma_addr_t \1'), + (CFunction('DEFINE_DMA_UNMAP_LEN'), r'__u32 \1'), + (CFunction('VIRTIO_DECLARE_FEATURES'), r'union { u64 \1; u64 \1_ar= ray[VIRTIO_FEATURES_U64S]; }'), ] =20 #: Transforms for function prototypes @@ -91,6 +78,7 @@ class CTransforms: (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__ +"), ""), + (CFunction("__cond_acquires"), ""), (CFunction("__cond_releases"), ""), (CFunction("__acquires"), ""), --=20 2.52.0