From nobody Fri Apr 3 08:06:50 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 5C7B3243367; Wed, 18 Feb 2026 10:13:18 +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=1771409598; cv=none; b=CwEkpIjOJTFjZiaqyQuUhbmiNwG22InREHFmYAz7YGt1kWEjm9KLrWte1EeW42oYT7dAsxf4lAfP8vw5nJWzjT0SyGizhusHSvjYO76Nw4o1hFeopJy0rCOyY9mroNtcsHFyKVccUllTN499UtLqzSuqym4r155JP1koaALn2WE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409598; c=relaxed/simple; bh=Mq94eCCs+RKATmleknUccsvrIqNogkHHQ1NGR1scPL0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=r1/qi2ys5MVbobKuZKGlDi8C1+XNCa2m9lvM45+TjRQTR79+TSAS/CkHh70vxkmsRdpZuRNsVhrxtCmk2G3WZIpKbbK7nnDvj3+5fN3VBOZFrkaZPiQzOpr6pfvV4g3xnhuinOVypl8m87YdfUltr7ddhUdPV6bBzXJqyAIyFY0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Y+9PRPJS; 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="Y+9PRPJS" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2914BC19425; Wed, 18 Feb 2026 10:13:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409598; bh=Mq94eCCs+RKATmleknUccsvrIqNogkHHQ1NGR1scPL0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Y+9PRPJSkjz11xvjOQGqeiX1T1CMS1ZijJxTf/OBtdeedFvvTx/WzQJZCMtcnEGLN oS7/wIqluqzChdEfIhT2PaNOIn4rle3aieEQKaqwQ1bos38Uz9YEhbr4GfYSJW0dIu yTXZAaB5WnO9cismVDnyNRH7HN6DE7B4OID1PEOUgCxsrnG3SDecUr2ybtaiXWLEdU Bi8UZNa3fBnmLnDcv3UMGGAKt9nnWjrreTjGradPefIWDS9W1uvq9Ag/6zA1D8pYFQ bsTnUA9BN/6ZIUVuw3zq+Yb2xzyKGoNBt9jvPGGv8hCMq8neI7CvkQny/kLPbdSUOJ iLqnG953iI+0g== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYW-00000000LKh-0WnY; Wed, 18 Feb 2026 11:13:16 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 01/38] docs: kdoc_re: add support for groups() Date: Wed, 18 Feb 2026 11:12:31 +0100 Message-ID: <49b2f5bd2284b0685d8a8ab363d60f89d4d53935.1771408406.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Add an equivalent to re groups() method. This is useful on debug messages. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 0bf9e01cdc57..774dd747ecb0 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -106,6 +106,13 @@ class KernRe: =20 return self.last_match.group(num) =20 + def groups(self): + """ + Returns the group results of the last match + """ + + return self.last_match.groups() + =20 class NestedMatch: """ --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 8E59433D6E1; Wed, 18 Feb 2026 10:13:18 +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=1771409598; cv=none; b=TXFJwwsIi3/25TrDrS7Dpk3tZ0g1iRiyRRCq04C9DfyTfw2+pQ6ABVuWcNPED0zk+QK37h6vQMzFT49iQQ55gLaT+PX1MHQAQz9ZG1ToW2XksCl2t1V5XEev0CQ03BRKk6hpE8AcIWGueY+YOHCHkYxj8GEblqKt6jNEBUl973I= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409598; c=relaxed/simple; bh=ZQpmZi3xCboNCaTitC+DH8Zwcl8IPzrA6Uao2EOU9sw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=j/sU0j5T9/xhpGlyZ+mEpYSKtRiTz4kX/bQiZxp9i079B044IvQVgZqzvVk0D4RMInmzn+BTHuzRqiYu5UjQtCEJFNQpXXFzxUsuxVQx88oVYltKs/a4qGPg6t5cqM4W7R3GvGLQRmkx3IGOoLQkQKEdrPih0F2WOQ6oWplLcYs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=V4mai1t9; 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="V4mai1t9" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6BE31C2BC86; Wed, 18 Feb 2026 10:13:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409598; bh=ZQpmZi3xCboNCaTitC+DH8Zwcl8IPzrA6Uao2EOU9sw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=V4mai1t9MrPfripNwkG+T4D2sdL2EKgkZEsiE7+/d1+6A635o536kp8D/PJk8JfN5 jY7ne68OA3MfMpRFOglO9rou7faRljM2edDo7w5fWjhhGT4z34ctWyOgLP5wIYc1Ka OAzHwdsccUyFXZHS63EAhy68OeW+dJ//KdcIPegB+ChAlHM+7s7Y/Y7VD1ZXrjM53x pCD8Nr7cqwwSDDKw0iWZAuQgDwoA/CxtRKlhxK36ZO32/k+CbhkaysSWLLq0gdKG1U Wl+8fR0RKi6gB/0XQPF27N05gWr3DJw5EqGz+mTuBFqW/uxvOsDgnTfO9Oqr4W3Kn9 CcKWiujG5to0g== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYW-00000000LMC-2DMh; Wed, 18 Feb 2026 11:13:16 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 02/38] docs: kdoc_re: don't go past the end of a line Date: Wed, 18 Feb 2026 11:12:32 +0100 Message-ID: <98da31eb6b5b2c84e960945e0ea283d3fcd2cce5.1771408406.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 Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 774dd747ecb0..6c44fcce0415 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -269,7 +269,7 @@ class NestedMatch: out +=3D new_sub =20 # Drop end ';' if any - if line[pos] =3D=3D ';': + if pos < len(line) and line[pos] =3D=3D ';': pos +=3D 1 =20 cur_pos =3D pos --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 E290233E352; Wed, 18 Feb 2026 10:13:18 +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=1771409599; cv=none; b=WcJADPfqUEu2JUypT7FQ9O9vKGHKdJenPIz8w9CAWecOEpml9IacIrayLD9+B8bUNEu2UjyJ6z2CJfsIhlIcR5c3z32SsxYJkBo9IcRqVSPuqueOaCGQaf6XzGM7gJXzWy+ZerCtKUpGB0HHNyyC6upNDA1zW637Iwzq0rawiZU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409599; c=relaxed/simple; bh=ftCwoMytpLULQWEXGblskf53KEc3VuT0xZwVGahX9Ic=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=EOM0qPmGyIOToa+PheOx9ygwAYAiBLy2GrQIAms9Fo4VH1PaP9lBFB3+uALjaoxjiYiu7tkh6nf1OlkcVfeJxKAEQshLVPO7WdYRlfOTkBpxh50MeWs3iOgxSg16BJ1Y+KkfCqgY4TpUKS1zhvm7B+OxRohOaZv8p1Yj2HOaYpQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=htrE8c65; 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="htrE8c65" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A3BADC19423; Wed, 18 Feb 2026 10:13:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409598; bh=ftCwoMytpLULQWEXGblskf53KEc3VuT0xZwVGahX9Ic=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=htrE8c65anRRdCdgeXC+2Nbg4/ppJ2ESBk6Jall7k/31EPTkYE2jsmZOkuMfS2f4z lBFZfKFDKoF+Yqf/85WHAeeJ03wqcoIjc9A4pqR4zU1GSmMEHpAAXxw4RY0i1mzWMH +Y8yKyZBC3ufsnEpSDq/1q9mZSIotnQ+fpO7j1KOY5Niw/Oxxapcq5CKa1A1ERcUch Nbjua0ThtkFERx5aSDmqY9rZSL2PCavnNs4iQMRhyssRwl1tWaihKZ7e7EiBnRgt6q cEI0Kpa04uQF7QY63Udc/i241ILXUXnTIYlVhz3PZmzgxO5wtpnJ1nAVlwp9fRtL36 iu1LUzH9VR04g== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYW-00000000LNN-3rfW; Wed, 18 Feb 2026 11:13:16 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 03/38] docs: kdoc_parser: move var transformers to the beginning Date: Wed, 18 Feb 2026 11:12:33 +0100 Message-ID: <117d010f42434c437284e37cb78a4590b84eb1c6.1771408406.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Just like functions and structs had their transform variables placed at the beginning, move variable transforms to there as well. No functional changes. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index ca00695b47b3..68a5aea9175d 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -192,6 +192,18 @@ function_xforms =3D [ (KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+")= , ""), ] =20 +# +# Transforms for variable prototypes +# +var_xforms =3D [ + (KernRe(r"__read_mostly"), ""), + (KernRe(r"__ro_after_init"), ""), + (KernRe(r"(?://.*)$"), ""), + (KernRe(r"(?:/\*.*\*/)"), ""), + (KernRe(r";$"), ""), + (KernRe(r"=3D.*"), ""), +] + # # Ancillary functions # @@ -972,15 +984,6 @@ class KernelDoc: ] OPTIONAL_VAR_ATTR =3D "^(?:" + "|".join(VAR_ATTRIBS) + ")?" =20 - sub_prefixes =3D [ - (KernRe(r"__read_mostly"), ""), - (KernRe(r"__ro_after_init"), ""), - (KernRe(r"(?://.*)$"), ""), - (KernRe(r"(?:/\*.*\*/)"), ""), - (KernRe(r";$"), ""), - (KernRe(r"=3D.*"), ""), - ] - # # Store the full prototype before modifying it # @@ -1004,7 +1007,7 @@ class KernelDoc: # Drop comments and macros to have a pure C prototype # if not declaration_name: - for r, sub in sub_prefixes: + for r, sub in var_xforms: proto =3D r.sub(sub, proto) =20 proto =3D proto.rstrip() --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 7EFDE33EB18; Wed, 18 Feb 2026 10:13:19 +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=1771409599; cv=none; b=YZk1z1Ty2iy5BsV/aF6bCUh6aYUsCDeAX1EwLVnNdE1L9VgSovs2UliU020tY2+tNbQ42M3hXsL2v/2IQo4TBJ/7TNihjPRPBTE6k2uXOIn2ypiTFaSIEoyJCOCgYOFI2+UJCG1WTZbl20AtfKyyppKD5Up+luCcVCFY0dScJjI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409599; c=relaxed/simple; bh=l1TnXg9K1HZGJE+MUFeDj5Ao7LGwzZBBWNXmq8OcdpM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=rQgbo95QXGAGGYtsv3JTSsNFbcDg5orjhaRaJwm44Ra9ei1n5lOQ9jsxyRKJiBmX8SJT0mmev3oImuru9W2iiuD68PMUSYd4KmjKfQJOYzhVItBPU+A/eThoA2+1RJJ9fUw3Br9wzaPHVPdjyyhyOza/xKLxR/jJ3LcQLMDE2l8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=MCvrIShR; 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="MCvrIShR" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 49139C2BCB2; Wed, 18 Feb 2026 10:13:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409599; bh=l1TnXg9K1HZGJE+MUFeDj5Ao7LGwzZBBWNXmq8OcdpM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=MCvrIShRWQOn3kud+SrF72GQRRQoy8OmrR6yjDW5RlNisEJFpIUqVjFy08irxCVc+ mjZgJcxkDMHVCNC8UshxLFNGBjByVeTTuuEgWLEWwnsvR1pmPN3/4xtswo9q/hiK9p gTyhtm4iw/YYOvpvJgtn8QfXn/lXb1oYxajx4Y5vMNt/hqvE1aU/NcV80bjSvHoFhz DlJryyoGqHz0vmCsAdDwilJwlqgOlKCISe1RoJf3A1lEtNw1Z3qQEiI+XmsGCvMldf Ac1SFPW5V1GguUfndsay9o6/+4fAj69FV+5wDZ98TJ55Alw7jJqSrmYU9TzlndEuii ELbd0z/ONbmnQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYX-00000000LOY-1StF; Wed, 18 Feb 2026 11:13:17 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 04/38] docs: kdoc_parser: don't mangle with function defines Date: Wed, 18 Feb 2026 11:12:34 +0100 Message-ID: <87e79a43714d1de8258c169bf2a8e2ce30705df2.1771408406.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Mangling with #defines is not nice, as we may end removing the macro names, preventing several macros from being properly documented. Also, on defines, we have something like: #define foo(a1, a2, a3, ...) \ /* some real implementation */ The prototype part (first line on this example) won't contain any macros, so no need to apply any regexes on it. With that, move the apply_transforms() logic to ensure that it will be called only on functions. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 68a5aea9175d..9643ffb7584a 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -163,7 +163,7 @@ struct_nested_prefixes =3D [ # # Transforms for function prototypes # -function_xforms =3D [ +function_xforms =3D [ (KernRe(r"^static +"), ""), (KernRe(r"^extern +"), ""), (KernRe(r"^asmlinkage +"), ""), @@ -1066,10 +1066,7 @@ class KernelDoc: found =3D func_macro =3D False return_type =3D '' decl_type =3D 'function' - # - # Apply the initial transformations. - # - prototype =3D apply_transforms(function_xforms, prototype) + # # If we have a macro, remove the "#define" at the front. # @@ -1088,6 +1085,11 @@ class KernelDoc: declaration_name =3D r.group(1) func_macro =3D True found =3D True + else: + # + # Apply the initial transformations. + # + prototype =3D apply_transforms(function_xforms, prototype) =20 # Yes, this truly is vile. We are looking for: # 1. Return type (may be nothing if we're looking at a macro) --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 0EBB533FE04; Wed, 18 Feb 2026 10:13:19 +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=1771409600; cv=none; b=VKFuoOPTEXXOj0OjYa5Uh2ce+oWYGySanA55YqOX3rSkSfA17L4hw+2LB95f8j6tnxj99XFQnOID6xx+lhG2EcOZPA9o0+97jcMNAo+OvRdvnMGosHqvCN/k7i1SCZhcTeckyALzUVTMhlOfilMbqrbJNhf4y3wuV3+dvjw/m+8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409600; c=relaxed/simple; bh=M0qmGyr3HuNHtOM507wR/t90o2hFNZdaNjjz4CqTCCI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=hWBTZxL0F4v07XQWzgRAB/XDFNPG/68OH18fOM4JKBs9twyM9pMlt8sjjqeLrspHCK5D8emGSo7VpmsXr9TlVe42qNUoPCSHHb0k90CaNK0g6J/ySp+y9pX+4f7MvY/RzXURkLetik5p2JABJAMwsZqjSmLpB59hK8cJTYCrqf4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=bKn4Oc/b; 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="bKn4Oc/b" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BD02CC19423; Wed, 18 Feb 2026 10:13:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409599; bh=M0qmGyr3HuNHtOM507wR/t90o2hFNZdaNjjz4CqTCCI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=bKn4Oc/bLsrS78n59qVcKj73TULTq/pLvB9eYi6SIqFgK/GXfjPPQ+oXWolwyFERD i8XPBpMogcpEBPp128ppIWlBEADNV+r2ITpQGhV72TZhd2JuxKhsd0YL0VHvy7zWtk NKr1H/0L9hkduGt+zYBiI+XoH1c36Mkcf0IIAPfqFOywdR514o7mLnd/lm2Z6m+LnN laxzwtVXo5KxE97Q5mKYgBakE1VEbW78DOx/it21E2FSrz8/9SQUk3EeXxu93TqKiK GlAFQyu9bR5ruRU7t5RT9ancwzYgPPJIG6HRZhAb+Wo0Z9QqBIssHLrIQafarn57Rl b7nRVg4YlnKDA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYX-00000000LPj-33OO; Wed, 18 Feb 2026 11:13:17 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 05/38] docs: kdoc_parser: add functions support for NestedMatch Date: Wed, 18 Feb 2026 11:12:35 +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 9643ffb7584a..af0ab732048b 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 # @@ -208,13 +215,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): @@ -409,6 +409,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 @@ -506,6 +508,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): """ @@ -882,11 +894,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. # @@ -1089,7 +1099,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 Fri Apr 3 08:06:50 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 210D133D4FB; Wed, 18 Feb 2026 10:13:20 +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=1771409600; cv=none; b=JRuk53Y1bH4LvZ1lbGffOXbgWcFr2rqB0frk0ZNXqamVaqHkOqqqTKFYLUluGCBqn/CHP7jWSsvVuTo6XrcdJGsgqD3GZGg1rHsL92JYhtyYdMUSX602p84GK3OdIMLuUPd20rAmSRAopl7Tgj4PouC3WKQ6fOGvXXNHSXHFeII= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409600; c=relaxed/simple; bh=gILK/WypmailkjOfO9MipodpPshzxrKnFuiIkYKk/rg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=hhW+41qbncUoxh0ACj3PtQtpW89A8QXjEXYz1tO0yKAyyrThJHfKoUruPTpVPYmprNBUojPt1pk+CPtHh0MXg0wZ3LSGP+NsCK4GwRb57cGFgYbdHEv23Ve2kPxXkc5Ny09LPwjpzj5fy0sRH15qfouZX5R77FfZup1CBANN8Ig= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=atAHd30A; 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="atAHd30A" Received: by smtp.kernel.org (Postfix) with ESMTPSA id DCDD6C2BCAF; Wed, 18 Feb 2026 10:13:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409599; bh=gILK/WypmailkjOfO9MipodpPshzxrKnFuiIkYKk/rg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=atAHd30ARTdvjh4o3OVEzdOoIfFmyPuQl5F5OjvxUz7NvPU24vgIa+IlnzJOMVn6r fotDv+alUGSOBwHcC8udpOj+pOXyyM7WKw19uboimQ9EQbMIOmJVrQqgf9WgJY4wZV XznuWSt+WhdIWUS2nnxrP978dshViXzVxf+pFp0r2q+tsnivxULuB12vcMFeVgOrvy xy7u2dmECOnxTDZaJR0gqDb2r4pif62jhxJ/adVJvdkU/sA64d6voHGcpGwKvOvKHJ dmLEOhP2LijmlXfG9jflrvQPiJIf2zc4iLdv5DNz08RI9499NXKHCEQKRS61zqltxg M7743dL15HR0w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYY-00000000LQu-0Rrg; Wed, 18 Feb 2026 11:13:18 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 06/38] docs: kdoc_parser: use NestedMatch to handle __attribute__ on functions Date: Wed, 18 Feb 2026 11:12:36 +0100 Message-ID: <1c9b6a151f41f1a6be5f503bd25e262f18baba10.1771408406.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 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 af0ab732048b..b704755d2f0a 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 # @@ -196,7 +197,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 Fri Apr 3 08:06:50 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 51497340290; Wed, 18 Feb 2026 10:13:20 +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=1771409600; cv=none; b=UhoD1KbEjiZuh3MUAItmq9VUo5/3NktQ5Q3Z9SJocuMd9VNBWK8+X9h7zuZ+9ZRSHRVXqEYb7b8gnGk8/p8d1SyWagLu4MH4rm/pFerAn6JcjJ8Jk4hcl/nKl+/RWwmIrsZ6nBPbwehLqidVMee0x09EfU0Euss/C5fagYMpNA0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409600; c=relaxed/simple; bh=oriSnGajTdXbMgaP9NfkyzvS+hRyHX9AaxdTAIMkPtI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=d852YqZbTgRDuZhOMCk37zahlvc5zk34RcJ/Pe1zsCg66eUDcMgIMUU8L9ryCGBEME4yG7Ecjyy/5DzvF3SApv9eqWnQwJTwx6IOOyExRbBNStQFSpBeedGhSxSvXviQcPQPXwquJ8Ov4AnIVFMeNMjVT36K9MGB/oZ0o5XWihI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=t9MxVgpY; 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="t9MxVgpY" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 31DEDC19423; Wed, 18 Feb 2026 10:13:20 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409600; bh=oriSnGajTdXbMgaP9NfkyzvS+hRyHX9AaxdTAIMkPtI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=t9MxVgpY2IFr8x/LKLcguDM3/lk4NPqx4Dub8TQIJCYpsy4h+B8T3w5UrbYJXz0mS hC5l/6KXNE6PuIWccTNV4z7yWwCZ/ecvqCpUSxMMH5ygCt7/cYq5+JEI5QFCde25Px tAe8OYCgn6hhz0BJphdv4E2oQxPVCKXYDhxj2x7Wf9S7NFPtLbl5t+do101ESm01sM w9lJ74yBEPqhRcjhsp+3wiCMi5IJQ0IwPY6ajH4vb2KQJxpPsAYqacmgcAVMswoZ7R xpond0X3jdAdrA3xxDbGQR0nUONAwfsnLu7m1QqhEVR2Qucvt7F4dfQvb0x96KW7Zl kvS76SE7gdL4w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYY-00000000LS7-1wTG; Wed, 18 Feb 2026 11:13:18 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 07/38] docs: kdoc_parser: fix variable regexes to work with size_t Date: Wed, 18 Feb 2026 11:12:37 +0100 Message-ID: <8c3a59498247039f45bd3b519651f958b0b4c0d9.1771408406.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 b704755d2f0a..b63d91b7f79e 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1028,14 +1028,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 Fri Apr 3 08:06:50 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 C2A3834105D; Wed, 18 Feb 2026 10:13:20 +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=1771409600; cv=none; b=K1nzeIROPCfVZKYnQFo82WesaHyTxXhfrD3rTiWKo/QI7s1W0BeNKaXDuDqMtS5OtLKHvqb2MC0mz2c7ln8wA95ChgsVcNN5siK+L9XYmYuu/7e75LGqRJPSg+lMRl3rcmw9JaB8lQytSQfDxUVWf+8qJkVXnXMKdQCZNqwgih8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409600; c=relaxed/simple; bh=SOaPcpSwL2YOZCy5eFxw6vXlh6YPzp2zJBUs62B0pPk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=UXaC9lZiwtVTXJVn+4ncDuYJ0c4Bl786Zf6Oy/j2iZcBNW16m5HcutgJ9TuOlBlavZJIcVKkTNHNNiNgTQLr54G4z+ilyPzjBb2D1RPgK9pTUXQrVb+fdW+j37EtvO+0Hwt+kNcOcKbWmnehHUEe12iaLWq/ZOqt+0eNKxThw5I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=hQKq7jXQ; 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="hQKq7jXQ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A4AB1C19421; Wed, 18 Feb 2026 10:13:20 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409600; bh=SOaPcpSwL2YOZCy5eFxw6vXlh6YPzp2zJBUs62B0pPk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hQKq7jXQAmnA1oi17FdW1WrT9lMnn/BxlrBnoB38O4kWhyj2xlLjtbM5SZFCp+kvw nnhJlECeI4ozMfT81rso4oUW/f/vIAHy4h2Vdg/sDz1xSMGvwpmDfcGoe1u+S5NEqN tPDK5O8K1r0+wDO/7rOmxS/ODjxxmVsa+CnhhUZpk/lHkJ5Mvr912Oz9Au/8FI8CNk s+364r21AxnZXLoAaXjf3bWb1VOqXDdmkeRY2HOKIeehkAy/Od4ZJ0VJ+QRTLoZIkd dogFzd2iBPNdPPLWXOkSm/0LZw4ek1MeGsLpDh099eFQsXCJklqXDA0YharYHMa4rw gpnjrPPbhFwYw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYY-00000000LTL-3hcM; Wed, 18 Feb 2026 11:13:18 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 08/38] docs: kdoc_parser: fix the default_value logic for variables Date: Wed, 18 Feb 2026 11:12:38 +0100 Message-ID: <6141a2f9378a79c76b3a8e860b82c46bc8bfb048.1771408406.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 b63d91b7f79e..abfa693051cb 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1036,9 +1036,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 Fri Apr 3 08:06:50 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 524CF33D6EA; Wed, 18 Feb 2026 10:13:21 +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=1771409601; cv=none; b=OW7/I88qoMvf5348TjwO7wBn8XK5J8zn+aIM5UyHRgf53IJDBR6rCWD9VCzteQEup+jao2yGVPV0a/EbB7G9/Da4R/B5DhhyAiYtwlQrVdwbgTG/NX9papQGT/R+q223tBZVX63GNGbS/KHqwVbm3+8QWM14ge7rCoS75O1dgHw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409601; c=relaxed/simple; bh=JTYFcIXcwV7BhIZmDYUhOQPoY48Bf1qGF/RzTiHfnbA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=uzbhRAa8leCC1FRmSVFLjIivztZswwZONgqZbvOYpezwLHdsrX3FUh2PC+2D7+y0oWu8XFbWvbZZwqVnsM2cWj6v7QsDsN7CmD8kwLq1192x/sKoSHuF5Ezr3KqQ3gYXkw1urc0xpMHW8OnrTD0Cju9x5gmUqrIllgL+hkBdwto= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Sj254GgI; 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="Sj254GgI" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 0F8EFC19423; Wed, 18 Feb 2026 10:13:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409601; bh=JTYFcIXcwV7BhIZmDYUhOQPoY48Bf1qGF/RzTiHfnbA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Sj254GgIyuBcb5XoikRrAgXbHGdZGs3odN22SIFqNLjd/14wf0z+iI7mVYs8rxoDs +cU85qUL3oHalhO35vgqdhYAgstD9Ptn+OhFqzui/HZcAhInoCK+UnjcdYx64Z6x/M TjWdCWjcTbAkhRyyFxoALGSHORs/7zdYIz2mFB+WNWDewvr6OZ5Ymbi7nL4bJfdlYo mK8oL/oDwlOxAomY+ZTtYqUwRg0Vm7lk5NUeFmlICVcvaGvjdlAtf/MJNrDAD1pHhL xjOmNqBFf7wNzhZHtEHT4oQb/0rXTu5OF6jmpdVNY4GyGxaAzJMPLl0q0BRadB+2yO TMZlNX8QAyjiQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYZ-00000000LUY-1NFu; Wed, 18 Feb 2026 11:13:19 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 09/38] docs: kdoc_parser: add some debug for variable parsing Date: Wed, 18 Feb 2026 11:12:39 +0100 Message-ID: <4d6cac070e812ba030474b2b814d31b3cdffa0da.1771408406.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 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 abfa693051cb..9559cbfd5e4c 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1034,11 +1034,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 @@ -1046,6 +1054,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 Fri Apr 3 08:06:50 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 7AAD0342C92; Wed, 18 Feb 2026 10:13:21 +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=1771409601; cv=none; b=OIueI+iTn4sX3FMDHEswF5WMsHW+VY2npeUYZtV7OvM2z/8TRiZB7e6X0WGSllDT0zqXP7lQi+Z9OGRW7G8JiWVT83eF3/ctVWONp2qaAbipdb+Vz7mckaIscCDO1Qu4MrAp6YTkkunwjyg00jBc1jT68eHb6gRVkUGQ1LqMRL4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409601; c=relaxed/simple; bh=4U9S92uLRAA+mWktHmpbTnn1LtPaRCq0xSK6dVoNpwE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=tRm31Y3h2ofAPLYFbzrHjY0igPIILNuJqPK0vylid10559v6ZucYuIhZryKIRTgUPb2NXqbygGHy74CmcJPiEhzF41+8mcxcGP9pjxuP4kUGF1AX+PRZltiEY2HVXJQ7XPsgXcwsyr1/B/cYmpLVEm5pw4eInWT/jWC5VX8vkhw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=rUD/rytU; 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="rUD/rytU" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 57C01C2BC87; Wed, 18 Feb 2026 10:13:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409601; bh=4U9S92uLRAA+mWktHmpbTnn1LtPaRCq0xSK6dVoNpwE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rUD/rytUPezekhvGG4gguYlNKlT0NYLFimevTVRcd45FYlndGdTYGxw8bTV6Jdi2J Mt/PB5/+kNrEnS8Exwz5EhrewWnsXSmeWQl0YqWEnFaT++QZSgWXoQmi0G8KhzgeI3 DRQavt8OfkLpJcZzzPPI6IrctkL0RM/8oqgVQHsrsAKv45NyjKZoi+OB9Ic/DoixTv LNl0/2H/4zpAIIq2w3y7cp7+j9JPs1Wr5ZDlHt4BGhbGWrG47oAqeilMOEaUyfHEFP ssHavLBu0u3s+iKiw2MMrbxl6KfBR9N9UmAtvdJTKgKgrLinVnjS0pp7TQ78wLgG9Y tIKQeBIymGc9w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYZ-00000000LW4-2dI7; Wed, 18 Feb 2026 11:13:19 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 10/38] docs: kdoc_parser: don't exclude defaults from prototype Date: Wed, 18 Feb 2026 11:12:40 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab If we do that, the defaults won't be parsed. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 1 - 1 file changed, 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 9559cbfd5e4c..d8e96c6c4ebc 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -208,7 +208,6 @@ var_xforms =3D [ (KernRe(r"(?://.*)$"), ""), (KernRe(r"(?:/\*.*\*/)"), ""), (KernRe(r";$"), ""), - (KernRe(r"=3D.*"), ""), ] =20 # --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 E3222343D7D; Wed, 18 Feb 2026 10:13:21 +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=1771409602; cv=none; b=Dc/hjhZ5qC99clzblhQoz1iukGZVPyHj0VaKdbh8HqMyL00x4LJ3mBvtMGgaKbQTeF+dsHuj+Cwx1fxhPc+pVtrztwkF79vb4GMIOW7ossIl6+Jcdkmndh34Gc/AEJ0b+6dFoSMFbnYyeJgPWsjfEffgkgusTpQdQfU9UW5KJ8Q= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409602; c=relaxed/simple; bh=4ie062/uAY7NEPbx8HftQesMKv4XY2PkHG2S9mIU+Tg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=S+6SEEtG5kCUmo5qwRzYMWyMecpZmHQMiXwOVD12EaJnkH9ERzhHNK58F6nqmSvBez4xwBu8WtfOuluSykYEw1mgZdrxcz8apiFFu6SCVvD5F7Bf9KGho4z4r66npt++QK+zh/6rS2cstWKFzn7PbCuhXleyFJBQF7iSqf074mM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=bZBY/1Fa; 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="bZBY/1Fa" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BFF90C2BCB7; Wed, 18 Feb 2026 10:13:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409601; bh=4ie062/uAY7NEPbx8HftQesMKv4XY2PkHG2S9mIU+Tg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=bZBY/1FaTnkXJUmGtrYofH1jQEkrmiDH3KpK/oMOiX4Il8R4zcJIniD3IhdIE89iD TU2dKrLM62QIp5pdYkTIq/mStnBg5nB+o6jSOfZpo78kXbwZZwAtbOOZrg3j2N1J85 k/354c4U3twO9yQeUdzuck7fSvOQlLJAbgymluH+vMuv5/fmRVQcXgC2CXUyH97UwX UsFyVRua0vtH7FN2nUSVuFpuM0sC9RAEY/m6qMd30gQRsDhJyhj4hG0mh6XNBMdZrG xB78oUuxqKOy4l/DKj4Srg8JPVJO+iSpfdWM8mY1XpTPvoOnloKFmKktwGWIxp5WSi LGtOUSyPF6MVA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYa-00000000LXG-0D7i; Wed, 18 Feb 2026 11:13:20 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 11/38] docs: kdoc_parser: fix parser to support multi-word types Date: Wed, 18 Feb 2026 11:12:41 +0100 Message-ID: <35ed0e29955ab12d67e22d451d03c7cf0a3530c3.1771408406.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The regular expression currently expects a single word for the type, but it may be something like "struct foo". Add support for it. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index d8e96c6c4ebc..f524385543a6 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1027,7 +1027,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) @@ -1038,7 +1038,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 Fri Apr 3 08:06:50 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 818DC3446BC; Wed, 18 Feb 2026 10:13:22 +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=1771409602; cv=none; b=bBxEoODat62e4KxfVROQvhAVUwnQ/WFIXlFzcMaOdNIxYTD5WRay+dQFon/R1MR1EoLTHHnhzQWQDl2qkxb9CnedRNGN4wxfa68siZ9JcsfSkMPZNCc4MdEq9afbC2x3WzcbbEcxcmsulORyPYKhiBnJ2T8TtxojlFcw17OCquI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409602; c=relaxed/simple; bh=o+XwvOhwzAMJSmWQIfpQC03ux6SeS1yBhcVlaWB7ox4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=nFh16VEtGeQiEFotl3ka7ldYFKt2eO5fKRssWOIjerpv0V2xGXwuARXyPR8CcCF5B28cVT94NY+/BVf1EnXVVOQsfwKJtFBDI34qNNlwKnC/zw0SRXo1pzbtAzHl8YeXMLnQVslbQngHuG9/VxMtEr3USNbAt8N+neZozHtSKlI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=dxqsx67i; 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="dxqsx67i" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5ABA6C2BC9E; Wed, 18 Feb 2026 10:13:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409602; bh=o+XwvOhwzAMJSmWQIfpQC03ux6SeS1yBhcVlaWB7ox4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=dxqsx67iD7IO8HPXRN3Njq0M9bTXSSPVhccyyOt+BvU+8mhOHNWJKTeRPQ3WU1wGP JEvWkInGLhAmbtvLtqlXpjQ8I3rUcYOnge7rcxAhhtqkrhkfdC0+peEYKiDixyes7G hmIcvO4cMhco9MCd1NM9ZCJ9gSTIwMn4Qk08HtihWVJK/L89NjhEQ/njBqIBIT2qlK /mGCNZDZ0Bqezgz3ezMCmJtMNojGBY8+4nSyJIlxeYdaeQRLx0nUm3YSKZjsgpFELS wvRq2xgVSAXmi/5Udqo5zEMciRQUzcqfIQmZ9r9xNQZY7cexbBcpoB07AGgpdpLMv1 djy3SvemE6+rg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYa-00000000LYT-2WjK; Wed, 18 Feb 2026 11:13:20 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap , Stephen Rothwell Subject: [PATCH 12/38] docs: kdoc_parser: ignore context analysis and lock attributes Date: Wed, 18 Feb 2026 11:12:42 +0100 Message-ID: <744ba47877b67b369e5c255438b7fdfe7b7efa25.1771408406.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab From: Randy Dunlap Drop 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 Reviewed-by: Aleksandr Loktionov Signed-off-by: Mauro Carvalho Chehab --- 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 f524385543a6..25d8a89f32b2 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 @@ -196,6 +208,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 @@ -205,6 +218,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 Fri Apr 3 08:06:50 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 C07BA344D86; Wed, 18 Feb 2026 10:13:22 +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=1771409602; cv=none; b=tFuOi0D5M+cuqzMS7wZCuEsWm98Enb7tV6/pDZCcTnoZL4sJiEnvRibErbakBX9/h8XBexTo1Iot7FazfrUX0HauGi5M+2ZnjrZjZzp53iDV0jXx5jXLdYgT+ywd/EM2SOAc2RoZxfMgNR/8ADjE+Yd8zyHZpabOXzq7XXgSJxo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409602; c=relaxed/simple; bh=ANXFSo26ZIet9VFxR9KfWGVyYc/Hjaq5uByQoaJKpUs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=katqYRDwgRBY+IySj+/N8xDaB6e+fnFycwmNqrlYu5EszcSabCRq17KyuZeqsJKgSDtea3wd9evER7gPG6DuHm+u7DqCl8/XJ/ukEIQeHCka5Xh+g17BsFtvjVhOPVjNyhcyy94DbRKf1WOOs287afaiv2tYz6a84WHXfDn3AdA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=GRoqqIpO; 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="GRoqqIpO" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A1B42C19425; Wed, 18 Feb 2026 10:13:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409602; bh=ANXFSo26ZIet9VFxR9KfWGVyYc/Hjaq5uByQoaJKpUs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GRoqqIpOh8KBAHdnmBPXjVRd1w+0ZswrOmO5iM3eQgbXb+mSGS7P4eoaqrstOeSJD kKyRiy8IA+Hr/ga9e79w+L7i7s33ndwthBktovkttS5y8DBBTlH3S8+VOJofTWU/c9 YQjZW4rPCEnbFi/QQduZObO6hYl4j4aHEBYT0tBJaReBlDtHPPecLl4pHYnb8fpZLC NrGN89fEUyL28wWgQUY2TMm06HUoWZVgq0h8sMRsYCyNGTH6sDQRAsFEsPKuQlbzT+ IECCDJohgVme3rhB49N/nz5j2gm5cDmwVlCEyL2yw+G3Ilt0SwLOZLdTvAagP3cy9G n6xAbFVPcZnnQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYa-00000000LZf-3pcS; Wed, 18 Feb 2026 11:13:20 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 13/38] docs: kdoc_parser: add support for LIST_HEAD Date: Wed, 18 Feb 2026 11:12:43 +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 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 25d8a89f32b2..6fe2fa032900 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -220,6 +220,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 Fri Apr 3 08:06:50 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 6BCF9345758; Wed, 18 Feb 2026 10:13:23 +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=1771409603; cv=none; b=jdGtkcE/GQhpyCl8K7fLJzpPK/b95LCHW1gDY7JClOAutBYTWRpgTEunL2+bskS1CeJRhpkitpSjFaSlVfuvxjeuaE26tKQcr6AplZm0enRpNO5zTGHu0SSIE0laD0lxfdcfOV249gkLuAEEJakdqFcEdAPd1to29U8DGHOgwww= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409603; c=relaxed/simple; bh=Z36YMV6EMn5rFyaqYGer/gsooo6w2VF9hIyZNnrWbgI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ohjxLU5QBJcoqmjTb9UeZ1mpYhwJotYSUep1fP3gwbkanGOdbjtUzy++Rtwy1z+hlUDvY153uV4vdAFxmNqkMFnzmwap5Jd3EaDlos+B5Dpm+jsHizeHsku+s7CBlizgULYYWNoMgt4txQPCTCxbJHhRVo9BdkNMnVXlgCGPi4A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=UZ7ngsvQ; 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="UZ7ngsvQ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2F518C19421; Wed, 18 Feb 2026 10:13:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409603; bh=Z36YMV6EMn5rFyaqYGer/gsooo6w2VF9hIyZNnrWbgI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=UZ7ngsvQWV+yF2K49kxsi+ciJK1WcKwWLhpRYok7EriWqUsYG1+ZzzpC98QV/LN3l x1hg94t3i7+rNvR3dLhbArDLu2YMg6Cgz4wHjYx5dP8V0WxTHPZP8ZxxOLS9t+WgD+ IIL/0twb+1YWHTgo+zBwRvaDxbQ92NJA22djnbAntcGyyhFRJ5Sd61HvkRTxrrMNqw 4rjOQAdWYdQilTEDOk3Lg8PZk+Oz0dEsSm8vVUfAY+OOhu5/krsuTYIqyCIsFEddnB Y99GPuDA43lOC6jikWdLaKoGWyHrIxSWs1EgSCCXQhcFxXbcTcE2mT7CdzZUy1Ieel /lQQzVLhf79MA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYb-00000000Lar-0nUE; Wed, 18 Feb 2026 11:13:21 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 14/38] docs: kdoc_parser: handle struct member macro VIRTIO_DECLARE_FEATURES(name) Date: Wed, 18 Feb 2026 11:12:44 +0100 Message-ID: <7b7809ce8ee561e6023a82288e3c429e9a1889d2.1771408406.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab From: Randy Dunlap Parse the macro VIRTIO_DECLARE_FEATURES(name) and expand it to its definition. These prevents one build warning: WARNING: include/linux/virtio.h:188 struct member 'VIRTIO_DECLARE_FEATURES(= features' not described in 'virtio_device' Signed-off-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 6fe2fa032900..32a30851db08 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 Fri Apr 3 08:06:50 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 635D7345757; Wed, 18 Feb 2026 10:13:23 +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=1771409603; cv=none; b=QsW9lFBJzpEK8icv0u8+YzcOZIsjeKlo23RnHNHknRVX1/4JA3Q7PY5kVtaieHit+7JMu/ww2nER+TYPOZPMsnTUuq/QtBdqA4ukY3udUrLJ4MFoa/VdekfUES22yKZ9fprz6+MzLV2AT4GvGEqnqPW6PJTmwapPaCLgRwPFYgA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409603; c=relaxed/simple; bh=2s+fzq6gQbWuB1ApycJQ9BmmsdbPbLOVTREB5x1uqxI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=nZXobOedcPWiW0uOmHUiEnFq5JkUgGbB712DFfEz1Iy0DA5F0pbjRDTiROq9aeWH/33+xHW9BYb/ivx7xgBQ09cuk/0krxI3Z51cZULS1e6THdYmHacPQQa5FakKmxm3UqwLYuJ6phgKU8JBg4Mb4pizr2drWYuid+tLRM9CRjQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=NXzlsSSL; 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="NXzlsSSL" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 46342C2BCAF; Wed, 18 Feb 2026 10:13:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409603; bh=2s+fzq6gQbWuB1ApycJQ9BmmsdbPbLOVTREB5x1uqxI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=NXzlsSSLNhbbqZv4lPRJrQvqahR3ZaCkRyRkFGnD6lg7Sy60W5BiePskmESRP/Cty Al/DpzbA4GpxnY4SYtJWZ5vowF3oLv4OTEQPtc6+J+5sNphAgmrH07REMm3xP2LJxH Ium9012IyjZQcYf/hl6TSD66MGlgCs6Bnz85TBnTW+as9GhtZUTi0G08kF9Fpa3EXJ mBSpw2KqNuN2kTo+wpsEjT7i+F74cTLDQwLWrdUt/8pwmxnouST8eJtr7jlRkuO6Za vGLJoV+iuj2C99MfdyjGtV5OW5J7Q8M9CtNXH3gjF6rtgHQATdS2nIuxVU7tMRyo4y zXJjPqeaV7j4w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYb-00000000Lc3-2Hp4; Wed, 18 Feb 2026 11:13:21 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 15/38] docs: kdoc_re: properly handle strings and escape chars on it Date: Wed, 18 Feb 2026 11:12:45 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The logic 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 6c44fcce0415..420cb8879ba3 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 Fri Apr 3 08:06:50 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 DDBE233E35C; Wed, 18 Feb 2026 10:13:23 +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=1771409603; cv=none; b=PLZfnINWIBnrvTop/Tm1BwqdMKTn0Gl0oQo7pVybJQdMhl/FFSJD+r9zJSrdEaFejYscxoh011ZsX9LeonrBaLCnvYKIKZqa6a+F4ieX3ftHuqsA9IbBY6rdFOwEQAfTMs8FjTL/pTMHVibmOg5gjQaawhgXOV7AJ6C+syshFfw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409603; c=relaxed/simple; bh=KU0YswEvwG2VkW3AG45CjZ2okRV/mwbS3lMGf4DpG8U=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=lbM5OTS/e1P+ImQ/MVdpMxsO1QOGbXz12sB+5uDfQbkw7QmqNG8f0vu/o1x7krSaBeK383O/DRW+Vo/ks0Q2YyVekanUQMt84j99hvYUKsU4TUiAMy5fhfIxqfM5fyQKchshNTk4q2PZBMaRxwG7Vh1NdZjTv/AYBR5ro4U4vvk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=AjCHRstY; 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="AjCHRstY" Received: by smtp.kernel.org (Postfix) with ESMTPSA id AB684C2BC86; Wed, 18 Feb 2026 10:13:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409603; bh=KU0YswEvwG2VkW3AG45CjZ2okRV/mwbS3lMGf4DpG8U=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=AjCHRstYcLRm3u4c4fawaisKaLhZHmBhWg1udI9djeLJzP+35BeRm04ViNsvVOyD0 70qhKifzCF6HrgWSr4hOtipPfZCZaNRUU7aqN1IncQgLe+2n/Tw3X+SD3urp81/ePC YPgVS8R1DVFQh3bvniBmgDDJhr3Nvw/IWOgTEbgf1vRfmgd3c20bSQej5CgOJVUU2e iQF4d1sN+7KFL3RjyHWrn6Xx3QxAJkvJOGhHnG6vTd0kgQZFpB0CRavnDHQOy6PVtm zCfrnRzDgiIQRXoZeRCysOMYeNVQPwGsZ7pMzX/mRSvdXRUcUo11ZVxiWa+FtsfkAl z3Iqswua2f2vA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYb-00000000LdF-46Fo; Wed, 18 Feb 2026 11:13:21 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 16/38] docs: kdoc_re: better show KernRe() at documentation Date: Wed, 18 Feb 2026 11:12:46 +0100 Message-ID: <497fbbcd66ab400c323c8840f917a8552fa801f3.1771408406.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab the __repr__() function is used by autodoc to document macro initialization. Add a better representation for them. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 420cb8879ba3..0a7f12616f9f 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 Fri Apr 3 08:06:50 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 3A52D346AD5; Wed, 18 Feb 2026 10:13:24 +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=1771409604; cv=none; b=QTBKKi6rw+xu0xIp82s2DTzpNnB5Pmd7nwZ1IHA3HzJPJbgoxHzqMBiTPJ2k+MullReDl0dUs6rYbCHJB7cLTg56lUH4gBzAoOFPA2wYZjn1MlI1MtpAPtf/S8FB5icAFAVlb5qXxbTYJMguAHp4T3DvUWINb9lcT5IrVqH8alg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409604; c=relaxed/simple; bh=G52yNr/mjvH//WKN8I/I22tm0myDjYubrgazvSxDbzk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Vk6HmKvZizNSJyKDJrCA4EaUnu7Y5hAcgg1kXybux56RmGetMBffgRqOuaNhEMPML3gGnPhpfiDbAQRN9HV0WhKESpOZmRC2cimu/OTsJzobekCLfTggjU6Km9tNQI612+V4L7g88pYxDTD5KV1Q7tewXzrc5JbxYliCC+GHItA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=YMZkDkUW; 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="YMZkDkUW" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 13517C19421; Wed, 18 Feb 2026 10:13:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409604; bh=G52yNr/mjvH//WKN8I/I22tm0myDjYubrgazvSxDbzk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YMZkDkUW13zBaRg7DOfUhjHz71unx7NaI6RyqKBl3SEQOD8c29gIcsjTXOy1Z9i2n 2Vakk440FbQguwYA+zpIKJOjV7418Okmq12espAksvQcRoemC3UF3ui4cWvKlhcwVT hLstPo4SK3w54q8W/Kwf53vmWMyv2tjA/FkMviJVveDHZjYTXX8uFnEo/D0i/Zg0Ft jBTtnLfbrlwy1YCNdCXx8/lF6PjLjeJWllaEaa28iJEG1PGSVnZiYTcX28bqzPeAVE S1hSlv2c8X7TdkjzC/DUP5X7SVle6Yrd04Hj1SpLw5Bual6mHAl/QTkBsm+jwYApZH C7nrIM/Wa/6YQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYc-00000000LeR-1Ov7; Wed, 18 Feb 2026 11:13:22 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 17/38] docs: kdoc_re: don't recompile NestedMatch regex every time Date: Wed, 18 Feb 2026 11:12:47 +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 Store delimiters and its regex-compiled version as const vars. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 35 ++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 0a7f12616f9f..00afa5bccd6d 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -99,6 +99,13 @@ class KernRe: self.last_match =3D self.regex.search(string) return self.last_match =20 + def finditer(self, string): + """ + Alias to re.finditer. + """ + + return self.regex.finditer(string) + def findall(self, string): """ Alias to re.findall. @@ -134,6 +141,16 @@ class KernRe: =20 return self.last_match.groups() =20 +#: Nested delimited pairs (brackets and parenthesis) +DELIMITER_PAIRS =3D { + '{': '}', + '(': ')', + '[': ']', +} + +#: compiled delimiters +RE_DELIM =3D KernRe(r'[\{\}\[\]\(\)]') + =20 class NestedMatch: """ @@ -183,14 +200,6 @@ class NestedMatch: # # FOO(arg1, arg2, arg3) =20 - DELIMITER_PAIRS =3D { - '{': '}', - '(': ')', - '[': ']', - } - - RE_DELIM =3D re.compile(r'[\{\}\[\]\(\)]') - def _search(self, regex, line): """ Finds paired blocks for a regex that ends with a delimiter. @@ -220,13 +229,13 @@ class NestedMatch: escape =3D False =20 d =3D line[offset - 1] - if d not in self.DELIMITER_PAIRS: + if d not in DELIMITER_PAIRS: continue =20 - end =3D self.DELIMITER_PAIRS[d] + end =3D DELIMITER_PAIRS[d] stack.append(end) =20 - for match in self.RE_DELIM.finditer(line[offset:]): + for match in RE_DELIM.finditer(line[offset:]): pos =3D match.start() + offset =20 d =3D line[pos] @@ -247,8 +256,8 @@ class NestedMatch: string_char =3D d continue =20 - if d in self.DELIMITER_PAIRS: - end =3D self.DELIMITER_PAIRS[d] + if d in DELIMITER_PAIRS: + end =3D DELIMITER_PAIRS[d] =20 stack.append(end) continue --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 74ABB346E51; Wed, 18 Feb 2026 10:13:24 +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=1771409604; cv=none; b=avZToxj7kQycWYL8UeIRI8a9QyX97gml9SbMCchQosgGl6QT8YEmVnCWXN/oNeF4zwdRr8hWdE7UwW3u6dwZtM96UAT0vp9vseoo772QnNtFjsSAHIRDfm6z/pMeagVmMehVNMJtXcrztLPLHjU0OLt/0dYga+bj+QiNgYyB8As= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409604; c=relaxed/simple; bh=lxqRyV3o4DNkRR+ET0M9mJXcj01vT7DB3Ke8NI6BKWU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=edGXaqfr58BPfno94o73dubqfvfmWIOG7FBVezZdgAdr7GXm+Qk9xteDstP3tY/bcZurxCOYvf1dQa0gbXisg80GH4/75U/IGlOsr4o7ie6tYu6DjKFZb1Cc79nU8yNer3CUKap8Mi8t3ho+JeiMWzJqscuuNDP9wOtIOm/LFbc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=hhN90xsm; 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="hhN90xsm" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 562EDC2BC86; Wed, 18 Feb 2026 10:13:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409604; bh=lxqRyV3o4DNkRR+ET0M9mJXcj01vT7DB3Ke8NI6BKWU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hhN90xsme2OpQoKScg+Ymx3ZPnjDy7G9dkB4NVgmtIPkagZU7INCyETmk4A71JD/8 nJTXnGOJ0hwHLa/W3ZTgs2hGS+YwTtr3O0Cf66QJzQX+TNYNADmA5droDseKoZYGJl BYhn64LMCV3+OeT06dfwGTvGjsEEfGcFG9pc3jefPv851r6gPflQyffjyHNZmuZ8bb FC3JtHpZ+2PviFdTsiN9i/zCc34BK/dBtbTFvzAaMWqqSF+e4PpjVBu5fdwjysvUgq TP5eXeAfChShpGnR0q9CPfEYtGnzf4burktNWKYsh6L++2lYPEmjpbLofnxaeHzTpp t82jf4AwAKR7A== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYc-00000000Lfc-2Xc1; Wed, 18 Feb 2026 11:13:22 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 18/38] docs: kdoc_re: Change NestedMath args replacement to \0 Date: Wed, 18 Feb 2026 11:12:48 +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 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 | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 32a30851db08..3ee169b505d3 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 00afa5bccd6d..2d83b6fb1cd6 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -291,7 +291,7 @@ class NestedMatch: =20 if the sub argument contains:: =20 - r'\1' + r'\0' =20 it will work just like re: it places there the matched paired data with the delimiter stripped. @@ -310,9 +310,9 @@ class NestedMatch: # Value, ignoring start/end delimiters value =3D line[end:pos - 1] =20 - # replaces \1 at the sub string, if \1 is used there + # replaces \0 at the sub string, if \0 is used there new_sub =3D sub - new_sub =3D new_sub.replace(r'\1', value) + new_sub =3D new_sub.replace(r'\0', value) =20 out +=3D new_sub =20 --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 4CBEE347FDE; Wed, 18 Feb 2026 10:13:25 +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=1771409605; cv=none; b=hpctUoG/RP8UmLqg+ODyOrnrT/FBIN+wTtWfkIRzvFQZguAESJ12vC85YCcb1r0YZQRAA1einCsdXBnHAVJ6HHueC8nWlKkmoXI9w1c679m4Gyvi7mBv5zSqkdVTfCjIXNGVDkOatcMP0JOTpTjHRm2OOb7ACbO4ihicaxe1XSk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409605; c=relaxed/simple; bh=DvfUwTuholX9BC+W38TUGNzdKlUVnreeYvd3PlaaCGM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=bLgmDXaVMoOfV620p7OqkDdut+r4S4vmLi/220ZwdRTl3oEVHE8JQRcEwvyC8JE+fopJgRKS9HMKAI58RqTQEh64UR/VqcpMMpFTcZ5t1tdMpmW0ksOrUJfOUJA8nkaiJczNoCySumKVzQ8MEhiZtgogEk0pPB6j7yaMQj5JAP8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=IO/JRtRA; 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="IO/JRtRA" Received: by smtp.kernel.org (Postfix) with ESMTPSA id EA9A3C19425; Wed, 18 Feb 2026 10:13:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409605; bh=DvfUwTuholX9BC+W38TUGNzdKlUVnreeYvd3PlaaCGM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=IO/JRtRAZj1btQXAZYuHO3FVv0sk70uvJvDQTiS/kTA63xY5Fm5GuSVHCJT8NDuuG bFxwUfGH+yckZPM2PpqfmzCjcrepNSH3JP3ACwMoAO+3uW2AFEj7FBwzRA9Xqp9tYF eOWuyp6YYdywv1b2hvvYjsPetFFraFwl6Nq1MmI9UFaAi2g7qupBtB7so4ix5GF9lO rX6543ISqBAgQeCH2r0+H94CdsqE41uPfCHjDIDR9gspPNDokPgCbBtGSDcuxndtKQ Uy7l+up6Flmx3XdfdoxvEBmCFlxecMfDAdK8Z7CBwhNbA7BSqPG4KpLBOt0rYVvWA/ L2oM/RY4AJpuw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYd-00000000Lh8-0uUp; Wed, 18 Feb 2026 11:13:23 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 19/38] docs: kdoc_re: make NestedMatch use KernRe Date: Wed, 18 Feb 2026 11:12:49 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Instead of using re_compile, let's create the class with the regex and use KernRe to keep it cached. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 55 ++++++++-------------------- tools/lib/python/kdoc/kdoc_re.py | 24 ++++++++---- 2 files changed, 33 insertions(+), 46 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 3ee169b505d3..06a7af4bfa57 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 # @@ -211,6 +186,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 # @@ -231,7 +217,6 @@ var_xforms =3D [ # Ancillary functions # =20 - multi_space =3D KernRe(r'\s\s+') def trim_whitespace(s): """ @@ -425,8 +410,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 @@ -524,14 +507,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, @@ -910,8 +890,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. @@ -1126,9 +1105,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 2d83b6fb1cd6..fed9894a5c71 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -200,7 +200,10 @@ class NestedMatch: # # FOO(arg1, arg2, arg3) =20 - def _search(self, regex, line): + def __init__(self, regex): + self.regex =3D KernRe(regex) + + def _search(self, line): """ Finds paired blocks for a regex that ends with a delimiter. =20 @@ -222,7 +225,7 @@ class NestedMatch: =20 stack =3D [] =20 - for match_re in regex.finditer(line): + for match_re in self.regex.finditer(line): start =3D match_re.start() offset =3D match_re.end() string_char =3D None @@ -270,7 +273,7 @@ class NestedMatch: yield start, offset, pos + 1 break =20 - def search(self, regex, line): + def search(self, line): """ This is similar to re.search: =20 @@ -278,12 +281,12 @@ class NestedMatch: returning occurrences only if all delimiters are paired. """ =20 - for t in self._search(regex, line): + for t in self._search(line): =20 yield line[t[0]:t[2]] =20 - def sub(self, regex, sub, line, count=3D0): - r""" + def sub(self, sub, line, count=3D0): + """ This is similar to re.sub: =20 It matches a regex that it is followed by a delimiter, @@ -304,7 +307,7 @@ class NestedMatch: cur_pos =3D 0 n =3D 0 =20 - for start, end, pos in self._search(regex, line): + for start, end, pos in self._search(line): out +=3D line[cur_pos:start] =20 # Value, ignoring start/end delimiters @@ -331,3 +334,10 @@ class NestedMatch: out +=3D line[cur_pos:l] =20 return out + + def __repr__(self): + """ + Returns a displayable version of the class init. + """ + + return f'NestedMatch("{self.regex.regex.pattern}")' --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 95B72348862; Wed, 18 Feb 2026 10:13:25 +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=1771409605; cv=none; b=dVUVr2PsN+S+U9U8pFlCoG3hTgeufonRWwOLjUiG1ZLwYKN7LDluEEj2Hx0Jlei3ndPAQEsvu2H0h/Iv5swkQDQu9bTl+E2f3LnTgX30D4YUw2e5pRWhtKdVvRgwMrHdMe+yYrfzVKv2pfff6f2ZUJeXOwtvshlHTDlxa5hb6DM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409605; c=relaxed/simple; bh=ioLa9q6sJJTF/v+qVABuiOCGnewuHvVB07azO/umkxY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=nPhBMXJCSVm+jlw4bEvDRjAU1GhsE2vjgRFQEZSY5l0TdayPlOlrNerACPrTOdrwm/Xmcd59AR9MmRNq3tawVGL3sMqSWpIvMmYvDBqQXuTKGjMOMtrMkbqBIob91q3oSCJaPrG7s5rn+xoiMFkmXCjIzm1dLxg8VA53oqo6RWU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=W2N8KsPy; 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="W2N8KsPy" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 76FEDC19421; Wed, 18 Feb 2026 10:13:25 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409605; bh=ioLa9q6sJJTF/v+qVABuiOCGnewuHvVB07azO/umkxY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=W2N8KsPyCPQzPnyyt5iGff8DGM/cK2sbMIH/1bvBNlb9V4D+29hAtxEEGQd3oPOnf C7xguU0Bc3PuPgb58uaRtNHDC5pI2XJ/gbpre0laoi4FfhdcqKOO66NykdGAiqXhaW xcJ12qRF8F5V6uKY86OvjofQJXS+IwVpUcDB0d6G72OA/rXHJKrzSdHKutEVsMBocC eVrQtYGIv6m5nRmSuJsioZds4HXl1GnWxKO92Lntgbwt+yM1pUm3BgK+3hTBnsUo8U M3AVqqBoOkwdHNyUa74CKCdOPfeHV33D5Kmz9WJ1gXsJ8H2ibOF7ipyaQT5kOgJiIx DC7V6XsME1wAg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYd-00000000LiL-35nU; Wed, 18 Feb 2026 11:13:23 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 20/38] docs: kdoc_re: add support on NestedMatch for argument replacement Date: Wed, 18 Feb 2026 11:12:50 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab 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 fed9894a5c71..05f36d665b70 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: @@ -313,9 +343,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 Fri Apr 3 08:06:50 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 F1C96349AE3; Wed, 18 Feb 2026 10:13:25 +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=1771409606; cv=none; b=aVhUDYBt2EsHHXlmzO3OYTXHKHQQ/TlL4xqEd1AOpCiuQ9H69neW7VtoIPlC7GLDf7LJUwJNYOXhv4cXE8M1kIAk4P8bn84pz09xPrLxWHKSyC842864eK2bTLP3EtJfwkZdj4p4KRNyzCrOohu+iKfilYRkNfRI72ntN+rTmzM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409606; c=relaxed/simple; bh=pTv8fyARiYUzN0SDULk8va6HhWxLlLCbC3eYwm4RiCo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=hVMgNnAUb2+Ct5Py6St9V4t+Ds6Y0yzCg5JjvClDjjXkXfctogqoZESU3BPO+NKWqX6OCkgLVvA44UI+wSHI+mn8w5gQAHZ0pvLkL+L7eXSb11iOpZaA+ynJQ8+2IdoTHBB2P2kECwx4/0fPq0G83iCEf1g2Pi56btFZN/7f4lA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=P3ChlR4b; 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="P3ChlR4b" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D2A9AC19421; Wed, 18 Feb 2026 10:13:25 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409605; bh=pTv8fyARiYUzN0SDULk8va6HhWxLlLCbC3eYwm4RiCo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=P3ChlR4bTE9lXd1SFNrL/stGx3aof4/2iZ+R4z2npTsJJzrL0y7iSZcs0aHf69M7Y YpCuS5UxLto9x8LI8zDheQxYMNMKWMBNpFxFfsaWt3S3rZXT32cXhmWFFfwQrXBnsU GP9d9Yv6BEakf0VD86lH4RNMBJVm8dphzPXA8UFwK10Dv5t0S/PRpA7JZEElgvHNlA sm1RyZwr3P/r4ntFzHfvJ3MSo3EbhNS/2fkf5EdJjwx/gAVfVisFqk2S0sYBXk5xYv ZL0xw8/GQuqQjXrjcIwF7GsUm3MiycxfP60XQYz+KcQzPLI3g+DsGjocPJzg6+N7P+ m9x6Zhlxw5l6w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYe-00000000LjY-0ayj; Wed, 18 Feb 2026 11:13:24 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 21/38] docs: kdoc_parser: better handle struct_group macros Date: Wed, 18 Feb 2026 11:12:51 +0100 Message-ID: <0f5400a1573288f9e0d48c34954ac9e769f83aa3.1771408406.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 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 06a7af4bfa57..b63a70f184eb 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 Fri Apr 3 08:06:50 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 6B18134A3D2; Wed, 18 Feb 2026 10:13:26 +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=1771409606; cv=none; b=Xk4MlWFHRBDbYb2dMvv+TuwBOSEtRn7F3iZXhakxSoq1X4WLK5eJoKqg1MSzoCL+2E5ig2vexcJylyVeGXpWm7lf7MnkURS1F7qg/sDagLBKWzBzIHGwaHHasTu8Bk2vgRlgTsRynH3Pn4E5GZVRvegJ7Gf243fV7v05WKcRz7Y= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409606; c=relaxed/simple; bh=HfA9d8T9A4lV+0318XofpC8IU2OubqTIaLYGnkL8N/E=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=KAoVCulRwTZUuidiDfuOOrXce27P+m2Ixm4AejmES0ejvcBKfmV1Y2GEodvwwiGvXDNyis+K1EaEfPXQyD4HOUCza6oyfdRMqyYiaVjevESVNMcOqc59PXbsxBdQ8ac1lnPGnl7TLdUfUEgjRiGSuc9ZEreCGU6qWyWSvdwPeio= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ppwqRnrj; 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="ppwqRnrj" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4EC54C19421; Wed, 18 Feb 2026 10:13:26 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409606; bh=HfA9d8T9A4lV+0318XofpC8IU2OubqTIaLYGnkL8N/E=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ppwqRnrjYO15gyib+5lOd1ODAKoyy3cbzAvuXAwJPFrtNqICxs3RAC8jYSWdmmMdZ ql7Usz87PIjZt1BVES3WLc1Jj4pNfTEZLv8XV5SqztnYc1eHRTBn4hx2uB4NEoXCdg BAl0ju2sz5gzWXVg6z9PQRha+zgKsZDZ6sAQG6u9Ey+DiUc4x8kzFfKnqpsBmK34Uc 7Boeesp9dD3r8quVIBzIUTC08TavKn/9m0lzBTcLixRwha1kN2HTwjcbroCcCJWJg8 ZNDQWYA2OvsPR++OMK/uvlCU2VWvEb5VNKhUXqp6CFfZSgDFp2yG43H10+9pxnrtx6 8+c6fmRkMdKNQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYe-00000000Lkk-2R7d; Wed, 18 Feb 2026 11:13:24 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 22/38] docs: kdoc_re: fix a parse bug on struct page_pool_params Date: Wed, 18 Feb 2026 11:12: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 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 Reviewed-by: Aleksandr Loktionov --- 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 05f36d665b70..cdc842f5fc8f 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 Fri Apr 3 08:06:50 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 085C334B1B0; Wed, 18 Feb 2026 10:13:26 +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=1771409607; cv=none; b=q5w05Sqp7XeB9O7g+WEhSieWMN/Hv16Y6FZp+Zjtos85R1VKtPEYi6+3Ka4MUMQXbmld6m06e8oXuXwxLgb3yGp/tVBAulthsxZyB8NWww2+ziBUS+/dHEFtNe9RgJtjHjIzeQp90u2AE6wJci+6D7p28TbJsChhdJqXGmTTk5g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409607; c=relaxed/simple; bh=86xDsz00XoZv72qsVxrMGG+DckqmwvjpK6jYFBlRKlc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=YmKURQRFtN4FSMvSRxb7X+EX8rHmQq9wMOHgxrsSO0KpGL2BLsQ8cXGpseGB4Zug+UdhyjXLX502eudD+9j2B97K9ey3IK5/mKzT0cnF18p92gUoSZMzhopXcXD53y0EzKVHG8bdsOV0TZeowq/B2C0kx6xtCoqUjTDTjXKs76s= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=iJgsNj1I; 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="iJgsNj1I" Received: by smtp.kernel.org (Postfix) with ESMTPSA id AFFA8C19421; Wed, 18 Feb 2026 10:13:26 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409606; bh=86xDsz00XoZv72qsVxrMGG+DckqmwvjpK6jYFBlRKlc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iJgsNj1ILFH/W404vgqOOGidsNLkMe7JdUEX16v4Uau/P2nB9asfrZh/MsBF6mG1p +dXmaF+m95974ysB4gS0Hdt73+2d0dETu3C4BvovzUrKcfvucv2NqxnM0kbuNcv1g+ yT/AEh39PjncL/tuEIYKGo6UfJVkKSh/W04IAWASLWUxWHrSokyUNVLThZiCIwgSNP X9tTUZq41lIw4eb4XKnGUr+/yWpCMbdQEU2VHjZh3G+tRj4bD+P1j/DRuPgijn6vW8 wczH34zjTznei9NFRqdXI6agVnpnSHAK5GvxBwwPB9G3X5Msy+nfKKFHtdlRFHwpo0 YlzAUxHzoIZAw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYf-00000000Llw-00lq; Wed, 18 Feb 2026 11:13:25 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 23/38] docs: kdoc_re: add a helper class to declare C function matches Date: Wed, 18 Feb 2026 11:12:53 +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 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 cdc842f5fc8f..f72b80ea4f1b 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -383,3 +383,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 Fri Apr 3 08:06:50 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 8EBEF34C81F; Wed, 18 Feb 2026 10:13:27 +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=1771409607; cv=none; b=mJv8jmGuRkIPF8hEIN50NkxTEuY/MHhXqNxCRXI7FfwNHdDK9t06FDkjQ538XOGVQsQeA9mcQwbjAR3g17BXih+zog9qGabPO9St0/xx2+DWGCwpi9H8slSpWYMkB9yiDzF/fRTaQjHM8Q2wOKOneO4XmkBK9TBwc+KQuIThPzs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409607; c=relaxed/simple; bh=LSo+D03oZi5uYnZP1zzS1JgRumV9SCEqB+7zq9VZC18=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=L7+TUsF4OHNlaHOLpEjMBKiSxewELSTS58e4pFc3sWBgANDRvjp9zt422wl2PFHDAv7yZMhdinj6u5JPP5Yn1mQWaIWmtsQzlF86urJ4t2+gHBWIc04FZoBtjDVbcmHmXwOrYGIvRLrcW+XNTBo2+ktV0mz3essTjOHm//AB1Uk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=fd3Y2AfS; 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="fd3Y2AfS" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 59838C19421; Wed, 18 Feb 2026 10:13:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409607; bh=LSo+D03oZi5uYnZP1zzS1JgRumV9SCEqB+7zq9VZC18=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=fd3Y2AfSZCLVb5ho0UWRUs58DTPrrOkIU7PSANmR8ki1jLt2DsXQ2ROs4qWey8qkA J50SoWlEXy1c02lhZfVCQnSD8wdxJclhGd1SGwaZi2YAoS4/vGmi+qQp9sgg+/EwZC ZkVhNcSvjx2gh4MVquWOXQ0g1bmybFGBRklgB7c2XYzLfQaxh1z+0B8n/PLSoWgXbK 4wVBJBNy1Rr2jw+rNVPFdTCByZ6wyMv7tZLaNMP9+ThwXv1Ppz3BoRY90kHq1RyVA5 fBhWlrLWbEnhUupj4ZE1juMVzNYwPg87WERnqEzAklV+uq0H2UdQC4d9AziGWxIAWa b2c4EWOzUHEEQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYf-00000000LnT-1nte; Wed, 18 Feb 2026 11:13:25 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 24/38] docs: kdoc_parser: use the new CFunction class Date: Wed, 18 Feb 2026 11:12:54 +0100 Message-ID: <7c62d09dfbdfa1c9ff26817cdd3a291775fa9199.1771408406.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 b63a70f184eb..e1914b2a6ab7 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), @@ -186,17 +186,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 Fri Apr 3 08:06:50 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 A7BEB33EB10; Wed, 18 Feb 2026 10:13:27 +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=1771409607; cv=none; b=rPTVrYLrAfNyKltEPRnuw0T1wELaLrSlvB/Q3x5+qlg97Dm09hNSSufiSHdwwGFX0SLCTAZdK4qmt9dWD3YzKpY5AGl7MEOC1eWvUWnwZEJPsM0ePdqO2m35V1uoVvcdeGcWGEwJ8wYiSsbavNrHj7VX5aBsw7cMpYFd81csMXs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409607; c=relaxed/simple; bh=ClRhaNpIRp4d1LeCk51dHxLXX4FD+ZDnmDB3anBLh9o=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=TBAYISBltoNqc1HdZPIVMsnEpHkrI2A/ZkmJvp9GqvBN/Je6sMMvUgfksZ5FZSCSFe6D2sYJrDp4TWhbUKWqP28kRSqBgf+ni5DD1e/EQmTK85f7+Q9bOD4bogX3f+rZa5TvwDXRS7WzDe9CfuJQAyPDNMoeaW310ouxy5YOOSM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=E4jW1HQE; 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="E4jW1HQE" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8ACFAC19423; Wed, 18 Feb 2026 10:13:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409607; bh=ClRhaNpIRp4d1LeCk51dHxLXX4FD+ZDnmDB3anBLh9o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=E4jW1HQEiNJGt9nxlWI7HPbPRCzBmC2z4/0V+SKXwbQCMFGfYkQQdUPUjxfK1785C 8peGmSJYA1db+nfNkQZMKfH8b2Jx6r0pjKIdjcmerVlhmbqNBDlRsD2+rdABgs2eiR dPC5cgWXdTKvgafq8jxD1ZeEdx0Xg6icPuDtdvyKN56CaKv0d/rOZIPUKwMZAPrOX5 ZsSIDLz68gsR3V/uCbF1dfdeYRAIWg9Kt1L5UnaW9MkDpZdowBgPVyvnbjpw7tRCzX x24RT1AdesyHRv3ptd19n8jamK067eY76BDnbcadlv/NTBPSMYfPhO3lByB7I9VNp9 8CEgVb48qVKBg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYf-00000000Loe-3OFS; Wed, 18 Feb 2026 11:13:25 +0100 From: Mauro Carvalho Chehab To: Alexander Lobakin , Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 25/38] docs: kdoc_parser: minimize differences with struct_group_tagged Date: Wed, 18 Feb 2026 11:12:55 +0100 Message-ID: <7b6f6ba86ebeab3d62735eb5b851631d042a361c.1771408406.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 e1914b2a6ab7..e735e79b5061 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 Fri Apr 3 08:06:50 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 0402434DB4A; Wed, 18 Feb 2026 10:13:29 +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=1771409609; cv=none; b=bimMHB9Mdo8lzQejxE5S7NgHZwqQap92pVX/A4EINgmZmXlXwFUxqZwNTUkjKLotyh0RHVkfmwayXdqRiNmXpSiu4YjSNv4mqpU/WZYxAZZ1Sy+52/WABvhoLfH5XtTjn7lL52MOFwXWluqo3oFvX1d2OAHXs5HgJ++Qsc4zFrM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409609; c=relaxed/simple; bh=3QK91KuqWdY00vyGOroyTR5vxbbyLrMwk3WJEOvMx9g=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=o9n5JGMZB3RHvzF4iNtwBiHcQcbu+c/fdFTlXw17yVidDj5tiq9OioSP5sPFpwcxfMYUD9fZqZsXGduNTrXMGpQwSsBIZ9IaLr9PhRTqm8oSD06TW+qFYq4zutozdclZbnrduTs7TRkxthdJaQVDz2bwzS1l5LxG8dpsFlsIeTc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=etEnEmCC; 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="etEnEmCC" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8A58FC19423; Wed, 18 Feb 2026 10:13:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409608; bh=3QK91KuqWdY00vyGOroyTR5vxbbyLrMwk3WJEOvMx9g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=etEnEmCC/c9IziG98TAAR4uadZWWirKhrzZMy3hZ++PLKrzTF3GF26q2tWLSIdj70 PqNSzpBYWmEUHZWxUqKvRvcYrYKYMW+zCQdUKk2/XL0iFsxiyhyLbIwemZje1i1NlW UI9czqhW8tqWm/11RFSvcTJRrZBDKeY+iSK07T1Dou/exea7pTASKQ8NZm7CTUwvDG z7BE4IAiLvUJHDpBJbqm7qlE5nRnTVoY52af63E05PDLcK7+HIGMwt1UvP3/12r1Aa qxz32Ov0D778k1QwM2QlCST928NIz1UsIexFSp0OWHr9yGh+Mpbqplb9ocAozwj/Lx +Y6znOhohep2g== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYg-00000000LqA-3IMj; Wed, 18 Feb 2026 11:13:26 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, "Gustavo A. R. Silva" , Aleksandr Loktionov , Kees Cook , Randy Dunlap , Shuah Khan Subject: [PATCH 26/38] docs: kdoc_parser: move transform lists to a separate file Date: Wed, 18 Feb 2026 11:12:56 +0100 Message-ID: <297f164226148f52b0b9a814086f51ade04ff031.1771408406.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 | 148 ++------------------------ tools/lib/python/kdoc/xforms_lists.py | 118 ++++++++++++++++++++ 4 files changed, 134 insertions(+), 143 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 e735e79b5061..a280fe581937 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -75,143 +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"__exit +"), ""), - (KernRe(r"__deprecated +"), ""), - (KernRe(r"__flatten +"), ""), - (KernRe(r"__meminit +"), ""), - (KernRe(r"__must_check +"), ""), - (KernRe(r"__weak +"), ""), - (KernRe(r"__sched +"), ""), - (KernRe(r"_noprof"), ""), - (KernRe(r"__always_unused *"), ""), - (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""), - (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""), - (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), - (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2= "), - (KernRe(r"__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 @@ -395,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 @@ -890,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. @@ -1012,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 @@ -1105,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..2e7b470c4e65 --- /dev/null +++ b/tools/lib/python/kdoc/xforms_lists.py @@ -0,0 +1,118 @@ +#!/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"__exit +"), ""), + (KernRe(r"__deprecated +"), ""), + (KernRe(r"__flatten +"), ""), + (KernRe(r"__meminit +"), ""), + (KernRe(r"__must_check +"), ""), + (KernRe(r"__weak +"), ""), + (KernRe(r"__sched +"), ""), + (KernRe(r"_noprof"), ""), + (KernRe(r"__always_unused *"), ""), + (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""), + (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), = ""), + (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), + (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1= , \2"), + (KernRe(r"__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 Fri Apr 3 08:06:50 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 51FE134DCD2; Wed, 18 Feb 2026 10:13:29 +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=1771409609; cv=none; b=I5iEA0ukexmRm3yR2FdzuEGFjG61AarSVzd2kFvJfhn/KaYX2SpcdpoQEJfetN7CBqTpi9p5JrRacYlTbXLopknLautl+YEC6v4qmCMq+ZCG9yNT5fJzldQW1aCdRoRQJkLhtw8LYVOK8XTdn/5TJjsWk83rwRsPKCAltloF7m0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409609; c=relaxed/simple; bh=P5m12KaIRlLZkIbryHITxBCt1b6WqbNCa3v60HgP3pM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=iImC5dTtDsIdY9j+gyrk/1gw+LzbEE/7MfZEYmRicYrKei5KI30hBL+KZkPtGOaIoMSY98xhYSoOcohxbByX+fydgw16Po9HNlRXtBqf/G0/5Y3a82NBDj+SUkdynKgNR7p9PwrGHlUXZV17WE5hlhOZGzbfx0AX9qE5J2gc9+g= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=AAcfGmf6; 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="AAcfGmf6" Received: by smtp.kernel.org (Postfix) with ESMTPSA id E8E00C19425; Wed, 18 Feb 2026 10:13:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409608; bh=P5m12KaIRlLZkIbryHITxBCt1b6WqbNCa3v60HgP3pM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=AAcfGmf63U6yk5n0NQY3nvBCQc9k0oCir9opirkc6aJj22+wR6i+ExY4JcFXV6lHL AlpJRtLXH0n8p7tzAOryvoSZ3bJYT0FTzib176Y21ZYCkhFkJjzyUBUudRykL+LAIV JkqNrDWo2oF1HI/eWoKXX9oYDtfA3fvHsERAk8kcdYLZA4I9H7IUreFLH54eGAEO3Y CXB9kn6Icb+6pNpn+2cWxQIkx1bVVSPHdAWU1YhBChEa6noGwMM4RdcNBRlwEoZlMN EOMOLG8k3FRMJ79uWF3keNgTU1suiFh/O/1Aa8TEMi36YSfCWjfUW9A2qELOzv9zCD kfEtW5H+6WcdQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYh-00000000LrO-0bkQ; Wed, 18 Feb 2026 11:13:27 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 27/38] docs: kdoc_re: don't remove the trailing ";" with NestedMatch Date: Wed, 18 Feb 2026 11:12: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 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 f72b80ea4f1b..e3809aaa0310 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -361,10 +361,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 Fri Apr 3 08:06:50 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 62A8333F395; Wed, 18 Feb 2026 10:13:29 +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=1771409609; cv=none; b=iE/OHayV76cyXuUKaDFjarPZbyBB8gi16A+42M1cWAwhO8nbuqJ0YI0xbgJg+c59nRo5wRjPoKEj7nZd0rmVZqpI+a6nhV7c1NIEmjUt94bxwFbZYbOulO9xXb2e/6ei8QTJJHeZUvmZ2rNULxC299/1JcPo7gLC2U0qLUKBjTA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409609; c=relaxed/simple; bh=yQBydwNaRIYMlzU4Ubfa3gdUJcPIj4ppbNTFE+NM7Rg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=tqLA3auLJr8k9jxDJrL0NMybMItxBnRRnbFOSxHJj/XOl31TVK5PJ70zpj/WfM9s/57qFLUaN+7JZjyn86/9GH6JlBP8o7NyGkbZnHYnicIBPIsyckyNpAMxlOKs5br+tPuDQJGzuolj62S/kD/cylnePRXhSC+xlgz3rY4wCDc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=nYJ1wD6t; 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="nYJ1wD6t" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 39346C19421; Wed, 18 Feb 2026 10:13:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409609; bh=yQBydwNaRIYMlzU4Ubfa3gdUJcPIj4ppbNTFE+NM7Rg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nYJ1wD6tseePJcKQKbRGVSxpEMfowqnIii6b7lTyIP7X3gOW6ouyFqT1d4g2obgZv D9EJKHEKg0KjkEPQgzNK+VHrRWm1pRD14A1yuHHb7FuejYCUasnbNPvJg74BF6NDt0 dXFEtVaASa+GJ4ENq4tXcaAyeo4B/TGRDlH0lzvWf7fHgdZTwX99oitgxNz0WSoSKT NUliYg2dFgzC/x+JPjBH55K/Th7gDFo71E9xxwtZAMfhu/xxLE7yCMJ4ZBrOSiCVQG rDvH/6/76wu+waqE+8vV+xRu/447e+OIlRnu3w7/+UPaTT1Js5edtbT/Qx8ik1sIoI 67z4X3b9j1WXQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYh-00000000LsZ-1yLx; Wed, 18 Feb 2026 11:13:27 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 28/38] docs: kdoc_re: prevent adding whitespaces on sub replacements Date: Wed, 18 Feb 2026 11:12:58 +0100 Message-ID: <24cce8e6d41b2f16698ac9f683b3f1df125e306e.1771408406.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 When NestedMatch is used, blank whitespaces may be placed after substitutions. As such spaces are part of the C syntax, we can safelly drop them, improving the quality of the output. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_re.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index e3809aaa0310..44af43aa1e93 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -344,8 +344,12 @@ class NestedMatch: =20 cur_pos =3D 0 n =3D 0 + l =3D len(line) =20 for start, end, pos in self._search(line): + while cur_pos < l and line[cur_pos] =3D=3D ' ': + cur_pos +=3D 1 + out +=3D line[cur_pos:start] =20 # Value, ignoring start/end delimiters @@ -368,7 +372,9 @@ class NestedMatch: break =20 # Append the remaining string - l =3D len(line) + while cur_pos < l and line[cur_pos] =3D=3D ' ': + cur_pos +=3D 1 + out +=3D line[cur_pos:l] =20 return out --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 D332933F8A0; Wed, 18 Feb 2026 10:13:29 +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=1771409609; cv=none; b=t5hQkWc56aY0i2fVD0zXwjYCcEbrGou3sHstKtehXKL3Z58mkuR99k4hZZ8AyR+5SwbTSHoTfXR1GwyLgnsd0/LKdr/1ApeFICp8ChyK/OFJAZP/GLGxXvYBQQszzS3igQeUWi9sOFwL1UIq1ELaH1b7+3Iy9ZqmRE0W+VG90wg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409609; c=relaxed/simple; bh=nnw4ho1Olbx2RNuzp7w4U3GO/hs4rZPbQud6YRRjsxc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=QNfO6Gy+/6yN+EXYXB0hZnrGdRO6d9UWNResN73fo5ZO50MpALA7WV6IZmU8kY0r54QOibxcRJ+dcI7aOo7Br12weWAj7LVEyMMay4wP0r0pyfy47Up9gdeJ8jsax98NFnBE2thZQyNxl2/Qek1RwMQNzrCX6X9UUtVAGToXHFw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=AK77plCt; 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="AK77plCt" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B37E0C19425; Wed, 18 Feb 2026 10:13:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409609; bh=nnw4ho1Olbx2RNuzp7w4U3GO/hs4rZPbQud6YRRjsxc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=AK77plCta9vdDWs0GEdINAHrUCAngMqf6VZJyUomLt0co3NpFjHCzl8X/SOBb+kzj gu/QhDCEDIuY1g5GiD0hd9noakpnLqeTu2GPBMn7DZuYs+6D22tucysb8NImprYMCH b4qrA+1YNUKgx902q1T82wzYYT6nAjNgTflIP5AHqiMTjKYWLrEun7jeyytDvLmgQ5 /6BrJcks8501xdmWQLiSGmRyYBNgehet/QEVblPoJs0myVj2wKBaLtHjcsoul7o0j0 Bg87zgXi1/JU1nEYSrf0y9csToMd2D2Z1TVLayclgl5PmesyY3Azvcbee+edpWi2Vy +A/86Otj5WHTA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYi-00000000Ltl-00lG; Wed, 18 Feb 2026 11:13:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Kees Cook , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, "Gustavo A. R. Silva" , Aleksandr Loktionov Subject: [PATCH 29/38] docs: xforms_lists.py: use CFuntion to handle all function macros Date: Wed, 18 Feb 2026 11:12:59 +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 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 | 71 ++++++++++++--------------- 1 file changed, 31 insertions(+), 40 deletions(-) diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/= xforms_lists.py index 2e7b470c4e65..6455850fee2d 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. @@ -86,12 +73,14 @@ class CTransforms: (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('__printf'), ""), + (CFunction('__(?:re)?alloc_size'), ""), + (CFunction("__diagnose_as"), ""), + (CFunction("DECL_BUCKET_PARAMS"), r"\1, \2"), + (CFunction("__cond_acquires"), ""), (CFunction("__cond_releases"), ""), (CFunction("__acquires"), ""), @@ -109,9 +98,11 @@ class CTransforms: var_xforms =3D [ (KernRe(r"__read_mostly"), ""), (KernRe(r"__ro_after_init"), ""), - (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ""), - (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ""), - (KernRe(r"LIST_HEAD\(([\w_]+)\)"), r"struct list_head \1"), + + (CFunction('__guarded_by'), ""), + (CFunction('__pt_guarded_by'), ""), + (CFunction("LIST_HEAD"), r"struct list_head \1"), + (KernRe(r"(?://.*)$"), ""), (KernRe(r"(?:/\*.*\*/)"), ""), (KernRe(r";$"), ""), --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 6319734F46D; Wed, 18 Feb 2026 10:13: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=1771409610; cv=none; b=ktcE00HGcd1JZaEaM2RTFonhwSsQyA0geoPZmwa12MVReNKNIa0/sMKXYXsreUwPBpXJiX9NZSzI4K72qkT1kHUz2adwdn9ayu7n/j6VliuDO0ILRMPnmvxmv5A7Ukj1Zs6YN9v53ygOIKra+jY0ZK03QqeJm6mU0hK27lnA73s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409610; c=relaxed/simple; bh=3n5zkoFrFUOIWGD8NapCIbtnoFCw7B0BzF+EBvzaUy8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=g4jkdsAPPM+13QwcJAVCRBlz+Ay8ZVEYp26P1SxqSvOBwWW4kva7/rudoMo+Nwtk/CZdwb+UyQZNoQrV8Zhx/LnsMlCoTkBAkkhQdmeOOImvV8iudiYuYVJ7AtB8aZV/8fot6FGxzhm9k8vrJUN7d/p03p/Cc4yLabiInPGKZ64= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=tcOYv7LY; 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="tcOYv7LY" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 23843C19423; Wed, 18 Feb 2026 10:13:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409610; bh=3n5zkoFrFUOIWGD8NapCIbtnoFCw7B0BzF+EBvzaUy8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=tcOYv7LYcrZ5Lrw7m9IiFT46WDG8lvQC26H6JL+ld2BPUJ/cRpb+fn46o6dyjvT3z fZ36++HlWV8B7DRuYo13mjduPE5fT8nnpO8Rv4MCt6ukJ39Dg+ah/qQ8tKt1Ool9pE 3hGfWgGufvONBSABEpw0bdqfPtL4E4y34ZLJMcjtnt7ZIKGQw92gavA/u+Xv+b6qng r9OUi0xaTOnNYXzwOI5k5FLzmWbtUL8ZKzpCOco0nDN+Bj3li2TGD1gTX25P+1WSN8 G+BraAGRnfcSmOEanFQ64tv8eoq/NABA9KyFjwEh8fSy0vvBTNR5DKd4utoDLvLdjg KXoPaETHcYK+Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYi-00000000Lux-1Xmg; Wed, 18 Feb 2026 11:13:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Randy Dunlap Subject: [PATCH 30/38] docs: kdoc_files: allows the caller to use a different xforms class Date: Wed, 18 Feb 2026 11:13: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 While the main goal for kernel-doc is to be used inside the Linux Kernel, other open source projects could benefit for it. That's currently the case of QEMU, which has a fork, mainly due to two reasons: - they need an extra C function transform rule; - they handle the html output a little bit different. Add an extra optional argument to make easier for the code to be shared, as, with that, QEMU can just create a new derivated class that will contain its specific rulesets, and just copy the remaining kernel-doc files as-is. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_files.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kd= oc_files.py index 7357c97a4b01..c35e033cf123 100644 --- a/tools/lib/python/kdoc/kdoc_files.py +++ b/tools/lib/python/kdoc/kdoc_files.py @@ -118,7 +118,7 @@ class KernelFiles(): if fname in self.files: return =20 - doc =3D KernelDoc(self.config, fname, CTransforms) + doc =3D KernelDoc(self.config, fname, self.xforms) export_table, entries =3D doc.parse_kdoc() =20 self.export_table[fname] =3D export_table @@ -154,7 +154,7 @@ class KernelFiles(): =20 self.error(f"Cannot find file {fname}") =20 - def __init__(self, verbose=3DFalse, out_style=3DNone, + def __init__(self, verbose=3DFalse, out_style=3DNone, xforms=3DNone, werror=3DFalse, wreturn=3DFalse, wshort_desc=3DFalse, wcontents_before_sections=3DFalse, logger=3DNone): @@ -193,6 +193,11 @@ class KernelFiles(): self.config.wshort_desc =3D wshort_desc self.config.wcontents_before_sections =3D wcontents_before_sections =20 + if xforms: + self.xforms =3D xforms + else: + self.xforms =3D CTransforms() + if not logger: self.config.log =3D logging.getLogger("kernel-doc") else: --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 CF2ED350286; Wed, 18 Feb 2026 10:13: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=1771409610; cv=none; b=WyvkmYPnkAe8/sYAbNrd8fS9TDq1k4c1DPJWB2/rYFWa+fmeqPyDCUZcSiqHuK0S9kJmrgZbXTKz4z45r+OSpZHw8cOIg2X8exCSb6b+kBQyRcTeB4TV6Hr8OC7du8q7pdVtXiDi2DbnyL2O8lpQragtaww/9qQQzV7p3cR9CX4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409610; c=relaxed/simple; bh=vr6braZddKgoYGrWnqS65Mye11jx/ixo713d+HFrhJc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Ve0M5gRqu1e4X/QLdNZ+ij88kHLkYCbl0RdhuMB83w+ZB+kJgCLhfsIXhCgztt2oII+uYFnvI4ASiBOrm5UKdMCyS+NPerzChD2FiUmn+q/Gsbt4StGzRzCXXZnK9QKzc3cNfPvArM3EzeH8/cpoex6RPECmfniCzRxEXndQ3r8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=TWlB+dWv; 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="TWlB+dWv" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9EE58C19423; Wed, 18 Feb 2026 10:13:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409610; bh=vr6braZddKgoYGrWnqS65Mye11jx/ixo713d+HFrhJc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=TWlB+dWvLoWppC8mBA0qmB5c3nDT2/AmirhXcP6cEGn2a7M25H9Gv7RhoYoSCVB5f 9rfe/g4ukmPFLVwz/QyYY/GZ8bChfo+tUv+oMVDLbOYDgP99PE70F8qLv1hDc1TDZ7 UzJnBBUTlZKsT7YiTlypFluMvPTfRLnhoSQhWUpVu35+hhLeBmEgIrxU2Sxb/TcPSv oxoqwpEeQSK11Hg4ko+Nedd+HTPVu8NbsPMzVMinYu8c3vSYxCK7+qctBqB0vjOxRl 314TDJCd6Rg9mvBwpfnMK5BBtOCdXMohntcGgJYwXhBp83SuKHjVkldBduyq6KIOYQ Nv++eFu1SYyJA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYi-00000000Lw8-3n8u; Wed, 18 Feb 2026 11:13:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap , Akira Yokosawa Subject: [PATCH 31/38] docs: kdoc_re: Fix NestedMatch.sub() which causes PDF builds to break Date: Wed, 18 Feb 2026 11:13:01 +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 Having a "\digit" inside a docstring with normal strings causes PDF output to break, as it will add a weird character inside the string. It should be using a raw string instead. Yet, having r"\0" won't solve, as this would be converted in Sphinx as "0". So, this has to be inside a pre formatted text. That's said, the comment itself is probably not the best one. Rewrite the entire comment to properly document each parameter and add a "delim" parameter that will be passed to the ancillary function. Reported-by: Akira Yokosawa Closes: https://lore.kernel.org/linux-doc/63e99049-cc72-4156-83af-414fdde34= 312@gmail.com/ Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_re.py | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 44af43aa1e93..f67ebe86c458 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -323,22 +323,28 @@ class NestedMatch: =20 return args =20 - def sub(self, sub, line, count=3D0): - """ - This is similar to re.sub: + def sub(self, sub, line, delim=3D",", count=3D0): + r""" + Perform a regex=E2=80=91based replacement on ``line`` for all matc= hes with + the ``self.regex`` pattern. It uses the following parameters: =20 - It matches a regex that it is followed by a delimiter, - replacing occurrences only if all delimiters are paired. + ``sub`` + Replacement string that may contain placeholders in the form + ``\{digit}``, where ``digit`` is an integer referring to the = regex + capture group number. =20 - if the sub argument contains:: + ``\{0}`` is a special case that expands to the entire matched = text. =20 - r'\0' + ``line`` + The string to operate on. =20 - it will work just like re: it places there the matched paired data - with the delimiter stripped. + ``delim`` + The delimiter used by identify the placeholder groups + (defaults to ","). =20 - If count is different than zero, it will replace at most count - items. + ``count`` + Maximum number of replacements per match. If 0 or omitted, + all matches are replaced. """ out =3D "" =20 @@ -358,7 +364,7 @@ class NestedMatch: # replace arguments new_sub =3D sub if "\\" in sub: - args =3D self._split_args(value) + args =3D self._split_args(value, delim=3Ddelim) =20 new_sub =3D re.sub(r'\\(\d+)', lambda m: args[int(m.group(1))], new_sub) --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 019A33587A9; Wed, 18 Feb 2026 10:13: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=1771409615; cv=none; b=DIKXpX0Gtcq5SNvPakPR6vyfcvhci2X2ASjFmYTOa5MIBTrZ2nzA++jTwcR21wimk6SE9KpSlSNy+aNiDEmSjxpVRUI1aX08JyskSfduL+clkkkIe1LVY5cZv39gTMuBsfBUH3FN1K5spWmtiMS14yrKbaJIGYPYIE3G/aFX4pI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409615; c=relaxed/simple; bh=93FI6HCbFuKLoTGysvIesP/671jVJYX05qdlxtKR9Kk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=I6gkn67e6PwvL3n6c2Hfda+AnQOK8yqxVJTKbjlprcmjl1Y5edSIX2Cm6iCeiYhNNJPXo4ZK/Gjz2fzMZvgmKDDrtxU2PtpMx50Izm0ybIRlnV3oNDOV+fq9Zh3bCvFLlpIdFxtcUVuVqjm5plSsx1M5s8/raEmT794ZjyhzHmo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=D6zqkt/3; 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="D6zqkt/3" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 26B82C19421; Wed, 18 Feb 2026 10:13:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409611; bh=93FI6HCbFuKLoTGysvIesP/671jVJYX05qdlxtKR9Kk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=D6zqkt/3NUB6EpxHEputgfvaw1vHtc0NsZ65QNN3AAKsJuHWSBcq82NKFzJu8llkR S+1bk/UPxulyqkqcMbYtUMX/IIRr09HFtRuwNOA1NPlhPHsSPUiXhECDzbmymTKCPU JmPJyAld8CPADXng3h49bxxTnDEx8O6tZ/7uUMOx2P8DlevrZHSEFbuD7SA01tAoZe Wy2GDlPrU1hQLkRN135ojO5oHWcW9ckY5i4kcvDUXG5i7xXrBHkp+i3T/cZga64Syq yIzxySQ3SnLG+PqvN40MnLlrYGZ278mb8gxtsx2bB1lNqpGUgxCJ6tFZMhIOwetkTl /MxbF5cjFyQRg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYj-00000000Lxe-1kJB; Wed, 18 Feb 2026 11:13:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Randy Dunlap Subject: [PATCH 32/38] docs: kdoc_files: document KernelFiles() ABI Date: Wed, 18 Feb 2026 11:13: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 KernelFiles is the main entry point to run kernel-doc, being used by both tools/docs/kernel-doc and Documentation/sphinx/kerneldoc.py. It is also used on QEMU, which also uses the kernel-doc libraries from tools/lib/python/kdoc. Properly describe its ABI contract. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_files.py | 44 ++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kd= oc_files.py index c35e033cf123..8c2059623949 100644 --- a/tools/lib/python/kdoc/kdoc_files.py +++ b/tools/lib/python/kdoc/kdoc_files.py @@ -91,7 +91,49 @@ class KernelFiles(): """ Parse kernel-doc tags on multiple kernel source files. =20 - There are two type of parsers defined here: + This is the main entry point to run kernel-doc. This class is initiali= zed + using a series of optional arguments: + + ``verbose`` + If True, enables kernel-doc verbosity. Default: False. + + ``out_style`` + Class to be used to format output. If None (default), + only report errors. + + ``xforms`` + Transforms to be applied to C prototypes and data structs. + If not specified, defaults to xforms =3D CFunction() + + ``werror`` + If True, treat warnings as errors, retuning an error code on warni= ngs. + + Default: False. + + ``wreturn`` + If True, warns about the lack of a return markup on functions. + + Default: False. + ``wshort_desc`` + If True, warns if initial short description is missing. + + Default: False. + + ``wcontents_before_sections`` + If True, warn if there are contents before sections (deprecated). + This option is kept just for backward-compatibility, but it does + nothing, neither here nor at the original Perl script. + + Default: False. + + ``logger`` + Optional logger class instance. + + If not specified, defaults to use: ``logging.getLogger("kernel-doc= ")`` + + Note: + There are two type of parsers defined here: + - self.parse_file(): parses both kernel-doc markups and ``EXPORT_SYMBOL*`` macros; - self.process_export_file(): parses only ``EXPORT_SYMBOL*`` macro= s. --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 A6F9633F8DC; Wed, 18 Feb 2026 10:13: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=1771409612; cv=none; b=m+EFWoqhlbxs94Cw4aFw5jD90sqTu5AkI04YDckUPvsiINM+OC6ep2sxRQNxJxFtjHH2lvoYscNI7FjIcD88vCV5A7o6847XtzLbe5EuafClg4Pq3G1D51tiV+HV+udLJjUJBc1niI6Jvz6fEGOP6lefNj5YAcpHvnjZL+d4LIU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409612; c=relaxed/simple; bh=CwHsRCLR3wmM4G7G9vnHWInI3q03RKTr8dBQN45i3sE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=IkuOiGU/nrYpVIBDXkiUgMuoSxugvdBhwLqCIIBPnGl1nOsx5680ciVJaTghcry5ITvS0nzncz5aVRt0qB+GIyRq6h0/xSMDlBnJQZbt2sqD/VFxDkuMFj3GNJMyhX/d8zxSE2+52/8vGxGonxprP4A9kmOcZ5zBno4OQ9WJrfk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=iX9EP0jK; 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="iX9EP0jK" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 88843C19423; Wed, 18 Feb 2026 10:13:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409611; bh=CwHsRCLR3wmM4G7G9vnHWInI3q03RKTr8dBQN45i3sE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iX9EP0jKJG8PffTHhAtfpwxm8+/JqYKhI9wEOAf9UsS609BzL4rTzoDyCS4yiTDHO fx6srtY75shT23w603e7nsB3DdtE9yxY9DmWMvsSYziUMzUe/lMUGIk6GSGbaA9qpw 5d78qxduPlfo4zZAKpcApx/5tk5bpxKp7byUKNLdkbgc1y2J5fEQbakS5OwypzeXFL zJylyilRu7/WBFcbI2os81lo8UyFUP8pe7lGFlwAs6DdczvN6b9Znbrj9drapcH+WP fvOOZAejGlAJ1FBQXc1tfBHK502VqdPOizOY1+9UWxvWy0Nvk2jYm5MKs53WJ2KRMa 8NEc6iPJZIs6Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYj-00000000Lyr-3Nye; Wed, 18 Feb 2026 11:13:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org Subject: [PATCH 33/38] docs: kdoc_output: add optional args to ManOutput class Date: Wed, 18 Feb 2026 11:13:03 +0100 Message-ID: <45e9f1cccffba1d8c39b9e439efe694e1426a717.1771408406.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 current logic hardcodes several values that are placed inside troff's title header (.TH). Place them as parameters to make the class more flexible. While here, remove the extra unused "LINUX" parameter at the end of the .TH header. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 4210b91dde5f..fe3fc0dfd02b 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -607,7 +607,14 @@ class ManFormat(OutputFormat): "%m %d %Y", ] =20 - def __init__(self, modulename): + def emit_th(self, name): + """Emit a title header line.""" + name =3D name.strip() + + self.data +=3D f'.TH "{self.modulename}" {self.section} "{name}" ' + self.data +=3D f' "{self.date}" "{self.manual}"\n' + + def __init__(self, modulename, section=3D"9", manual=3D"Kernel API Man= ual"): """ Creates class variables. =20 @@ -616,7 +623,11 @@ class ManFormat(OutputFormat): """ =20 super().__init__() + self.modulename =3D modulename + self.section =3D section + self.manual =3D manual + self.symbols =3D [] =20 dt =3D None @@ -632,7 +643,7 @@ class ManFormat(OutputFormat): if not dt: dt =3D datetime.now() =20 - self.man_date =3D dt.strftime("%B %Y") + self.date =3D dt.strftime("%B %Y") =20 def arg_name(self, args, name): """ @@ -724,7 +735,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{self.modulename}" 9 "{out_name}" "{self.man= _date}" "API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" @@ -734,7 +745,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{name}" 9 "{out_name}" "{self.man_date}" "Ke= rnel Hacker\'s Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" @@ -780,7 +791,7 @@ class ManFormat(OutputFormat): def out_enum(self, fname, name, args): out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{self.modulename}" 9 "{out_name}" "{self.man= _date}" "API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"enum {name} \\- {args['purpose']}\n" @@ -813,7 +824,7 @@ class ManFormat(OutputFormat): out_name =3D self.arg_name(args, name) full_proto =3D args.other_stuff["full_proto"] =20 - self.data +=3D f'.TH "{self.modulename}" 9 "{out_name}" "{self.man= _date}" "API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" @@ -834,7 +845,7 @@ class ManFormat(OutputFormat): purpose =3D args.get('purpose') out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{module}" 9 "{out_name}" "{self.man_date}" "= API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"typedef {name} \\- {purpose}\n" @@ -849,7 +860,7 @@ class ManFormat(OutputFormat): definition =3D args.get('definition') out_name =3D self.arg_name(args, name) =20 - self.data +=3D f'.TH "{module}" 9 "{out_name}" "{self.man_date}" "= API Manual" LINUX' + "\n" + self.emit_th(out_name) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{args.type} {name} \\- {purpose}\n" --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 0317B352C43; Wed, 18 Feb 2026 10:13:32 +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=1771409612; cv=none; b=ioJK0zodUZw1HoJQI9y4ntZjZJlmNzqFKEnr5sMZUHPMsg6tGoqRm1reETEnvKexd6s47B+1E/PPwx7oXNluc3CTk1DO5/G2sQeVrpreYL9PXyL0mq0Nijr2J/2zaQSl8yTqJxWp++NG1R+0XmBKQ874qjWujcQ9/U4coKzBjPo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409612; c=relaxed/simple; bh=J9gpBcUhWSmksHEje7HfFrvd/UJKiZjrUhxoxqAfK3o=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Q8XwflTzUJ3I2TaLjTKMmkhJMCp/6ekFEPei14E4FofVepMWrM9Tv+bYaCV6Rfe+j/czxam0RpzR4+fLx7bSh6gyg6/bpY4SLheYLjaEZ+0/m3APcy1Jlj9Q01q3sV20jTtYgJFxXZczOATCjVxymwOcfo20cKUq9pXTfZlmbLo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=HGaRpMRO; 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="HGaRpMRO" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D8102C2BC86; Wed, 18 Feb 2026 10:13:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409611; bh=J9gpBcUhWSmksHEje7HfFrvd/UJKiZjrUhxoxqAfK3o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=HGaRpMROqM8qzVFGoU6huHazI36POCwMiUwUU3rvaf7mizJI7r7BYYXt5NPl0ZIX2 rl4YDhZo7lFrS/0MQl5Vb+OI8DimUdQo+H9NbpOOb5g8Uqyf7w8U53PBJzcGIw9oWf PpncsMHuc134d0WmDE2dFuaWdQr102z+sKsRKrzIo+PlL1sPrzXi2Czv9SLMpIfjAh RcYgv06eKI3xJk4qgGaMZIAJ3gjTMn8CY5Zdp53QzvGfzh7d2aCPEqJquICd5nuxzv 4GI5MM+TUvoRebTWS8p/m3B7dIEJPRWJOf38Mv+811CCAMloTtZ2C/jc6LHmFMeBfX aWLw+TyMJ2kgg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYk-00000000M03-0i2s; Wed, 18 Feb 2026 11:13:30 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Shuah Khan Subject: [PATCH 34/38] docs: sphinx-build-wrapper: better handle troff .TH markups Date: Wed, 18 Feb 2026 11:13:04 +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 Using a regular expression to match .TH is problematic, as it doesn't handle well quotation marks. Use shlex instead. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/sphinx-build-wrapper | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index b7c149dff06b..e6418e22e2ff 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -576,7 +576,6 @@ class SphinxBuilder: """ =20 re_kernel_doc =3D re.compile(r"^\.\.\s+kernel-doc::\s*(\S+)") - re_man =3D re.compile(r'^\.TH "[^"]*" (\d+) "([^"]*)"') =20 if docs_dir =3D=3D src_dir: # @@ -616,8 +615,7 @@ class SphinxBuilder: fp =3D None try: for line in result.stdout.split("\n"): - match =3D re_man.match(line) - if not match: + if not line.startswith(".TH"): if fp: fp.write(line + '\n') continue @@ -625,7 +623,9 @@ class SphinxBuilder: if fp: fp.close() =20 - fname =3D f"{output_dir}/{match.group(2)}.{match.group(1)}" + # Use shlex here, as it handles well parameters with commas + args =3D shlex.split(line) + fname =3D f"{output_dir}/{args[3]}.{args[2]}" =20 if self.verbose: print(f"Creating {fname}") --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 01A653587B0; Wed, 18 Feb 2026 10:13:32 +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=1771409615; cv=none; b=GBgDQbZPSuMd+PyPNJxH9tuLcgY0WNB7n6D+G5KrbeGqyzjGRvH/+fdrXG++gs+hiuByY7OPogJ6HPiGyuFu5MZ6F8UMQfbsUiq/I84cNg8PVmts1Y8vwCMWrto7IOkfHS4wtj3LQPOuoZCwIrIUMSHyaj0MM3X3b7hhCeWl3Xo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409615; c=relaxed/simple; bh=xc3bdeTKA4gaQTm1QPUjzckBF1/Bc6XutKPIezxeXB8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=uvZvpp0iesc7hH63ELS2hcFAER9nSZoOwoTc5RGW8HwPmpq6HCl/DNzP4glWkD70k7idiunlm0cAdJYAhvxmrpgSP8KdWaJKofDdjDC/1hUio7Eh07MF2ejMSx3jG2x2Y8Rb2HwTdVBcZRQLyMm8DWSNPQbUISIGhsknWLOYOPE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Jab6p8eK; 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="Jab6p8eK" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5B929C2BC86; Wed, 18 Feb 2026 10:13:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409612; bh=xc3bdeTKA4gaQTm1QPUjzckBF1/Bc6XutKPIezxeXB8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Jab6p8eK+HQmF5tjAbh1RwIRwC3EdK+p02whFrMgbAKP5lSvhER9feNwMXqDPhc64 5X/4X/2/pOuXsOEBQOFIsKPAWmqp4gzDoGrw/PO9uw40FhAnPGF+VPeeKS3BTzLXAN pYvBkQSIcAuYbQGeyADrf27SKdnKYZTlNDdQNMgSHggfqjf856QeIpSSyjq2QcU+yu GhayWNugcI4K+ZCL9cpld4j91yvFK4FdZBuGZQLYW6AifoGFcp1256O6OeeenYWM1C DXwKXObNYv3LLa6/PkV+FB9mmUazt1sW2jhvDvyhKsfmG8Q4bNGTL4bAf77fgQJ6d+ vTWUOohGPS+Dw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYk-00000000M1F-2cOl; Wed, 18 Feb 2026 11:13:30 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH 35/38] docs: kdoc_output: use a more standard order for .TH on man pages Date: Wed, 18 Feb 2026 11:13:05 +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 generated man pages are not following the current standards for Linux documentation. Reorder .TH fields for them to look like other Linux man pages. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/sphinx-build-wrapper | 2 +- tools/lib/python/kdoc/kdoc_output.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index e6418e22e2ff..ac6852e3dd8c 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -625,7 +625,7 @@ class SphinxBuilder: =20 # Use shlex here, as it handles well parameters with commas args =3D shlex.split(line) - fname =3D f"{output_dir}/{args[3]}.{args[2]}" + fname =3D f"{output_dir}/{args[1]}.{args[2]}" =20 if self.verbose: print(f"Creating {fname}") diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index fe3fc0dfd02b..fb44cc8e0770 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -611,8 +611,8 @@ class ManFormat(OutputFormat): """Emit a title header line.""" name =3D name.strip() =20 - self.data +=3D f'.TH "{self.modulename}" {self.section} "{name}" ' - self.data +=3D f' "{self.date}" "{self.manual}"\n' + self.data +=3D f'.TH "{name}" {self.section} "{self.date}" ' + self.data +=3D f' "{self.modulename}" "{self.manual}"\n' =20 def __init__(self, modulename, section=3D"9", manual=3D"Kernel API Man= ual"): """ --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 01B403587B3; Wed, 18 Feb 2026 10:13:32 +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=1771409615; cv=none; b=aLxA6teDJDnmdwdbbvBiyP4887KOKpVCxLYbh96/J06QSM7hmoZBt2EERmv6EVbAzgrrYCkhxU9Z3jpo3XkI+JY1nhQdGL5C3mssereBPnuTmm+s92UGVKXTZZv5t7X3STdyfeVwePCJ99LVJRKz3uLnFT8A7yNhwmqZ8bxfz+s= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409615; c=relaxed/simple; bh=StLiyG6YMI5Qu+bnXMhDG5SBpIn/ZhlyGc1i11g1b5g=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=OVhD0IKyHm7TlwfjPblIBMT41jaPP/dBBVYN55phYmgdkkyRnarbg62mC2nCwtxSrzO5gG8grhj3ilb3lg0ifxb/rMds2r9CX8Jge070196mXvWPGV8Zlq/rcaNN+iYwJIOB9v5NVhr9IlpvOn0pwDCfkv1y73QuyEWFpgLa178= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=PH4vkffY; 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="PH4vkffY" Received: by smtp.kernel.org (Postfix) with ESMTPSA id AF45FC4AF09; Wed, 18 Feb 2026 10:13:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409612; bh=StLiyG6YMI5Qu+bnXMhDG5SBpIn/ZhlyGc1i11g1b5g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PH4vkffYkqJW5ZJe/JehvYwIYLyV37DkmsbCHziw3ZVSjHd4EliM7zDIQlCjtaU0Z U20j9CXVrMqrxjt74/nCU9pV909y8KZl7Kx29eAoi8pHbTaHCZLWLqkh0edxn8F33h QhfzO7VKCgJy8x9eg+oCwr7h+SKHdBib2ixx09YOEGwNjsXBz0bgbAciMULtmq/712 qSIDw4AlysSb8aejoFbM1yB9o2t+2EKb+dpOlHYIaTBUE40qW6WQhk48HGObOlaVOV uQe3rukCNq0ZZnYRv4xNIusCcPOxhwpL7RkYt8ha0BbOjd6/BhAVtz7TQY6WisSC5M 3yIFoKlyOeSpg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYl-00000000M2R-00ln; Wed, 18 Feb 2026 11:13:31 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Shuah Khan Subject: [PATCH 36/38] docs: sphinx-build-wrapper: don't allow "/" on file names Date: Wed, 18 Feb 2026 11:13:06 +0100 Message-ID: <343c89692a53b256670c1bd393aff2159dc3faa2.1771408406.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 When handling "DOC:" sections, slash characters may be there. Prevent using it at the file names, as this is used for directory separator. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/sphinx-build-wrapper | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index ac6852e3dd8c..d4bb1175fe32 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -625,7 +625,8 @@ class SphinxBuilder: =20 # Use shlex here, as it handles well parameters with commas args =3D shlex.split(line) - fname =3D f"{output_dir}/{args[1]}.{args[2]}" + name =3D args[1].replace("/", " ") + fname =3D f"{output_dir}/{name}.{args[2]}" =20 if self.verbose: print(f"Creating {fname}") --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 5241B354AD0; Wed, 18 Feb 2026 10:13:33 +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=1771409613; cv=none; b=D3XuN4/wNWNChkFFSJeOpeopstoU+A9IiKcZK0m0UPFivOcdU8+lx4KKsedcOYKdI8xp9Hq1sk5n1h+1Ryhc6mVj8vqY82zc1porHb4TzlQutQwjMePC6c4Q02+wRktxbDvbVCXvqpdnHG3aYcfopMItiHKFOIWP7Qff2HZSfIE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409613; c=relaxed/simple; bh=3P9hiqMJWs99bANIe05s+PiDHBtg0dmIB/Ud7yaibWo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=eKJxdRHCVD0kQYHBII6CXiFHcJYJOCXEB6zHLF57qU5PYohpIp9hH2j85DFlSchlDVimdG38bTapn9HNWz3L/eQS5T+gzREHEtyNuONNa4IorwbBg6yHj0bAFq0aI1YfEM5C1+uh33uWei46ep9JBaBh7RSRBwJGhkmUieKoFLQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=BIqwfoV+; 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="BIqwfoV+" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 355F5C19423; Wed, 18 Feb 2026 10:13:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409613; bh=3P9hiqMJWs99bANIe05s+PiDHBtg0dmIB/Ud7yaibWo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=BIqwfoV+v2/xOuRN3E350Oc1l18+qkwnx9/6fTKNR5zqTbMATC7FyhCuXooCYEFv+ nuM+zMKR0Dkz76X0z+E27ndHyVP60cR4SY0EnFxlB/tmE9dpC2E6vxiaTrzzNrQCgq N/s/PVLmWVtxqkDYYgqml5YXJxERJp9sZnI8wxLeuPkES5tQEw87AGs+ijfiuzH+9d 8aY7C5sLaHyfK00lC4HG4/4qB022KabQuKgPsjpyUY+Ph4W2czJRHO+lgACqw0A7oE n6rLK0qfM05yTq7X21eGyzrHxkfKv12GCRxxBtH+72jVUmcsleSjOxBtcSALVF/SWd 8rjjIjpYU76FQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYl-00000000M3c-1jrv; Wed, 18 Feb 2026 11:13:31 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org Subject: [PATCH 37/38] docs: kdoc_output: describe the class init parameters Date: Wed, 18 Feb 2026 11:13:07 +0100 Message-ID: <260f2d989f4187940e371023dc8a035c28521b8e.1771408406.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab As this class is part of the ABI used by both Sphinx kerneldoc extension and docs/tools/kernel-doc, better describe what parmeters are used to initialize ManOutput class. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 29 +++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index fb44cc8e0770..1e3dc47bc696 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -580,7 +580,34 @@ class RestFormat(OutputFormat): =20 =20 class ManFormat(OutputFormat): - """Consts and functions used by man pages output.""" + """ + Consts and functions used by man pages output. + + This class has one mandatory parameter and some optional ones, which + are needed to define the title header contents: + + ``modulename`` + Defines the module name to be used at the troff ``.TH`` output. + + This argument is mandatory. + + ``section`` + Usually a numeric value from 0 to 9, but man pages also accept + some strings like "p". + + Defauls to ``9`` + + ``manual`` + Defaults to ``Kernel API Manual``. + + The above controls the output of teh corresponding fields on troff + title headers, which will be filled like this:: + + .TH "{name}" {section} "{date}" "{modulename}" "{manual}" + + where ``name``` will match the API symbol name, and ``date`` will be + either the date where the Kernel was compiled or the current date + """ =20 highlights =3D ( (type_constant, r"\1"), --=20 2.52.0 From nobody Fri Apr 3 08:06:50 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 001C03563E7; Wed, 18 Feb 2026 10:13:33 +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=1771409614; cv=none; b=THfdkkx4PMSbhSGt7JJnP2d81U2pa+hxdUBMFdLxpCvB06Zz2KhDOYqah5LC/u0QUbSOJJ+EukmtLunegajNYv8Y/1CHmT+NCdUOhPiCLCe2qJ6VOdmuabBJc5aafiT+2l8BoN5LSKdK8YWkasYifKWmB3n59J9iVXQviaI+Xek= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1771409614; c=relaxed/simple; bh=fvMjJpvYeiR5dsEmac23+IArGmOBOLOmIiyyzQVBvqE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=PMKFitAWbedQ47DRgKVNmdw8nOm6dWzURkyazwC1jE2Cm9G7R4V8EA5Ieo/jqR+Ywd1cH4zox5cLAAWzR5QGy23RgMC+fw+Uy3Xm8AMJ7W6Olv7dQzfarHN9bGXr9nUOlfFPo6s24X7dXCwtFveQXn1VDf5barUmU+VPxaHXEdU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=XCXs+vDn; 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="XCXs+vDn" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D708EC2BC9E; Wed, 18 Feb 2026 10:13:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1771409613; bh=fvMjJpvYeiR5dsEmac23+IArGmOBOLOmIiyyzQVBvqE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XCXs+vDn55NbKpqXTFsPi7CJOEdjC9jxLinK6EHOS/f1g9uf/z3PDR5iM8HgJvv2N mw6006xk6eMPrrhZWZ3gUeQXlVDshIklV6mSZyA2lgJ13YDwgHo2gn2K8nzXG/bpJP n39uFySI2zwLYiZOkjEYdwgNtOW2LtrKhR7rgIWrEZRbzr7rC8K23c/KG2zdDUwpV5 UOBj0eJUJmFgIO08ARmNG+Siz2Z6OmI5KuPjSBDbx9dowDPlrvTK01Sir9ICF4Ut/c aEvWGuUJcbwKyygGrOWVxR2JEgz6iA8qCHMFu5BmbAekRIl1Bf2Y2UDdWBfrOFHzN+ 45IuDdYQRZx+A== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vseYm-00000000M4p-0GPz; Wed, 18 Feb 2026 11:13:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Shuah Khan Subject: [PATCH 38/38] docs: kdoc_output: pick a better default for modulename Date: Wed, 18 Feb 2026 11:13:08 +0100 Message-ID: <45159d8100d22567a592a90769a71a5335f0a085.1771408406.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 placing the same data for modulename for all generated man pages, use the directory from the filename used to produce kernel docs as basis. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/kernel-doc | 1 - tools/lib/python/kdoc/kdoc_output.py | 41 +++++++++++++++++----------- 2 files changed, 25 insertions(+), 17 deletions(-) diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc index aed09f9a54dd..3a932f95bdf5 100755 --- a/tools/docs/kernel-doc +++ b/tools/docs/kernel-doc @@ -210,7 +210,6 @@ def main(): help=3D"Enable debug messages") =20 parser.add_argument("-M", "-modulename", "--modulename", - default=3D"Kernel API", help=3D"Allow setting a module name at the output.= ") =20 parser.add_argument("-l", "-enable-lineno", "--enable_lineno", diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 1e3dc47bc696..44e40a6e8ca6 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -589,7 +589,8 @@ class ManFormat(OutputFormat): ``modulename`` Defines the module name to be used at the troff ``.TH`` output. =20 - This argument is mandatory. + This argument is optional. If not specified, it will be filled + with the directory which contains the documented file. =20 ``section`` Usually a numeric value from 0 to 9, but man pages also accept @@ -634,14 +635,21 @@ class ManFormat(OutputFormat): "%m %d %Y", ] =20 - def emit_th(self, name): + def emit_th(self, name, args): """Emit a title header line.""" - name =3D name.strip() + title =3D name.strip() + module =3D self.modulename(args) =20 - self.data +=3D f'.TH "{name}" {self.section} "{self.date}" ' - self.data +=3D f' "{self.modulename}" "{self.manual}"\n' + self.data +=3D f'.TH "{title}" {self.section} "{self.date}" ' + self.data +=3D f' "{module}" "{self.manual}"\n' =20 - def __init__(self, modulename, section=3D"9", manual=3D"Kernel API Man= ual"): + def modulename(self, args): + if self._modulename: + return self._modulename + + return os.path.dirname(args.fname) + + def __init__(self, modulename=3DNone, section=3D"9", manual=3D"Kernel = API Manual"): """ Creates class variables. =20 @@ -651,7 +659,7 @@ class ManFormat(OutputFormat): =20 super().__init__() =20 - self.modulename =3D modulename + self._modulename =3D modulename self.section =3D section self.manual =3D manual =20 @@ -685,7 +693,8 @@ class ManFormat(OutputFormat): dtype =3D args.type =20 if dtype =3D=3D "doc": - return self.modulename + return name +# return os.path.basename(self.modulename(args)) =20 if dtype in ["function", "typedef"]: return name @@ -762,7 +771,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" @@ -772,7 +781,7 @@ class ManFormat(OutputFormat): =20 out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" @@ -818,7 +827,7 @@ class ManFormat(OutputFormat): def out_enum(self, fname, name, args): out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"enum {name} \\- {args['purpose']}\n" @@ -851,7 +860,7 @@ class ManFormat(OutputFormat): out_name =3D self.arg_name(args, name) full_proto =3D args.other_stuff["full_proto"] =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{name} \\- {args['purpose']}\n" @@ -868,11 +877,11 @@ class ManFormat(OutputFormat): self.output_highlight(text) =20 def out_typedef(self, fname, name, args): - module =3D self.modulename + module =3D self.modulename(args) purpose =3D args.get('purpose') out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"typedef {name} \\- {purpose}\n" @@ -882,12 +891,12 @@ class ManFormat(OutputFormat): self.output_highlight(text) =20 def out_struct(self, fname, name, args): - module =3D self.modulename + module =3D self.modulename(args) purpose =3D args.get('purpose') definition =3D args.get('definition') out_name =3D self.arg_name(args, name) =20 - self.emit_th(out_name) + self.emit_th(out_name, args) =20 self.data +=3D ".SH NAME\n" self.data +=3D f"{args.type} {name} \\- {purpose}\n" --=20 2.52.0