From nobody Sat Feb 7 17:55:25 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 0CD6D3542F6; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=BVqauaq0Vku5dwH8+lt+e1biLp++D09DjFi2SbRGrhBr3FQAKA3YOuREY3F6GYteesRc1F156qljdj+R0GDrP7VBCyeHv4hn611ILH1U6QYd5w2lUXLoXIWu/pvV2c82UpH9Gzzvm6IH/BpjHkoM5ylZuVaV5UY3erCXhkacFQo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=gMIMQCBzXE8M1JL5w9F3R5TyIvM3vcLDpK3YDNHeLyM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ki9zeVGLPYO+iPzez9xz3eavR33Lqms1SRNJleRQINEju+wqaht3h+vLqdisP2E1Vpqrta5D3GfmXJ+wuI8skwXFax+qrcxL9lcZ0A/udyIBvaC7/mJgDF0E9s0K2/Vv1B+Wq+6Av+1WPU056kvQPEqwrvbSnLnX4X2iv27QBiw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=itzFgM1h; 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="itzFgM1h" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 74611C2BC9E; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=gMIMQCBzXE8M1JL5w9F3R5TyIvM3vcLDpK3YDNHeLyM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=itzFgM1hHQtINK9Tggf9nZluKqT1tfa33omgqV7sSa4Pogr/jZmmS3rJPEfY3DhiN QjKK5oCCmyQxC2pIqEI/guZsIXdLh+bFKIPOZ4Ne6UrbsC3Ysdg768tiB3tP2XdNU0 IcP01cHajYZ2ff9yXY77rkpq0Iusq3XNv80hFLcy0TGna1bsaBIDkEclwuzxRgpOwf amm4WJguATio9mS6n0oXrQ6vic4mPWBXPwk2VCUI5NgF/5RCKmwmF0rNt8GrR4O4lN mnv3YsyHSG7vayq2JYn4QRUwmnstoq6Jz9YIGGoglJLdhetsm6rMpeVwT1I3u2fQu1 Ywk2eSmwuk4QA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVjo-1Mqq; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 01/41] docs: kdoc_re: add support for groups() Date: Sat, 31 Jan 2026 15:24: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 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 2816bd9f90f8..19e777e2c97e 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -106,6 +106,13 @@ class KernRe: =20 return self.last_match.group(num) =20 + def groups(self): + """ + Returns the group results of the last match + """ + + return self.last_match.groups() + =20 class NestedMatch: """ --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 0D5D635771C; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=B4Wee1Cy2RUPKrLNNqtI8rYj1WwDvkICK14vyKN3JmLbplaD4fIPsW4OOakB3O1FBGWf0kBPaSwmZMT5Gr8nOEioi1Onj03dHqwbZIrGfmDnW08FbfJXwSJEwrL0dl6zdscvVo+dXWyBA6KrZeJmIoks5ARU1s2KXftwziRKJXU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=cDzNSL27IncK8WPRKmlP9JMukq5yWhzhTMzDMh9MrSM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=LVov3wBEDYfTMwKz5YobSNymkxXie2BUcsJacFdPIliGLBFAXYcPa39dKP/5bIL92iuV0oW/o2C1vUlgl+M7Tmt3vqSPs/po6NysBdVRugZPi4/mtBRJl+BMxeWsXJddWlkjLjbGNFlBUM69vmVRZbchmNPXB36rPKHiE7qLyvI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=PEDWcGd3; 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="PEDWcGd3" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6E77CC2BCB0; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=cDzNSL27IncK8WPRKmlP9JMukq5yWhzhTMzDMh9MrSM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PEDWcGd36euZpi8nOiel3TXpYdJOL8abL9z7ynodbLLhy6rzLqH6A8vSGVIswFiDA 3y5hQspd0NPBIj/tAoDiMDAMaRyJ9qyRI3pSP1lif0B5157uLWHc6XKebCgeHgxaaa whWaaVTQKCyrRQUroRgucN/UNavm1g/fH50aiq6ALDRfF+g1TiLRrSX4AAhuZb/luH trXAg7Lp6wQYMHHRMh3baqgO/j/SwREzI1gjamVgtw8pwvJpTjeFCqUXf+Y5XIjpBn FefP8nlRqqX6DwsYD353Icu7UoRIRA0woOB1cHIzO3Kj+ErLdVj+KJg84eorZ3P47G LBDnMRsAFsxGw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVjs-1UXg; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 02/41] docs: kdoc_re: don't go past the end of a line Date: Sat, 31 Jan 2026 15:24:36 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The logic which checks if the line ends with ";" is currently broken: it may try to read past the buffer. Fix it by checking before trying to access line[pos]. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 19e777e2c97e..a0402c065d3a 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -265,7 +265,7 @@ class NestedMatch: out +=3D new_sub =20 # Drop end ';' if any - if line[pos] =3D=3D ';': + if pos < len(line) and line[pos] =3D=3D ';': pos +=3D 1 =20 cur_pos =3D pos --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 C7014354ACE; Sat, 31 Jan 2026 14:25: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=1769869521; cv=none; b=Lk4uuYVRkEeWi9vjM4viKrRgmIANj3DoDkFMcsBYs5Ltjg1B4evuoHTANOY1NsRKcHqA46Pi5Yxg/GodJc1xzJM0+Y4vq4eHSNs2sqW1ZLf7uC1uD4dx1v2qFm2l9T18Xj4eW3t1nrYq/qUeSKEe3Cs1ptgkVyCV3d2hXG2tUFo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869521; c=relaxed/simple; bh=a6lkkyCGl+XetcnP8/XAHQbs/mIXiTfJmq3uiOJoYsc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Vh0TT3K/Dfsu1UiSfHmkThKNo/Ho2vOowcaVoDT+9356GDVaNapqDCz/8WYsjSJbiqUqHfu3z01LWXS6E52e/9bEgX2bWrKXuw+I0tg6mgVrI72wXXemKaH8X39af8CZ6CCuyTGljJL5g3GVn/G35z55Dr0DBWu6rjwJrH+L6Q0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=B6u5o/al; 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="B6u5o/al" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 66F0EC19425; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=a6lkkyCGl+XetcnP8/XAHQbs/mIXiTfJmq3uiOJoYsc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=B6u5o/alVJagTQ7ZiNo2WcIAEFBEGkXfokP+2uYASByjtfTxwyk4pFLgDCtEPwoHr PxMm7Obl/uy0ipJ7M6zAVf/yoPOKjLXRsk1gnyUlJufdMYVq0bZ4fVqsDthHPI/hmI uN0Bo89oKezlv53rTBHOcm3k+gPbNcXVmoOiPZX7v79oPVd1M2rEt3CJEYTYuuS0lB mg15INJEDvO4ZYZksPOARNdQ0Vqx73OD9BYq2szwL54HODmw6BpQP0GrlhkrZ0D5yM A4/IiKDCshiFpZO1MxXrSnvXIav2dhiKhO2zvtV3ByZzOBXWbrH9o1YCqJh2j9IHUA V/BF+NoiyZC/Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVjw-1c9g; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 03/41] docs: kdoc_parser: move var transformers to the beginning Date: Sat, 31 Jan 2026 15:24:37 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Just like functions and structs had their transform variables placed at the beginning, move variable transforms to there as well. No functional changes. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index fd57944ae907..0b68b140cd02 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -191,6 +191,18 @@ function_xforms =3D [ (KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+")= , ""), ] =20 +# +# Transforms for variable prototypes +# +var_xforms =3D [ + (KernRe(r"__read_mostly"), ""), + (KernRe(r"__ro_after_init"), ""), + (KernRe(r"(?://.*)$"), ""), + (KernRe(r"(?:/\*.*\*/)"), ""), + (KernRe(r";$"), ""), + (KernRe(r"=3D.*"), ""), +] + # # Ancillary functions # @@ -971,15 +983,6 @@ class KernelDoc: ] OPTIONAL_VAR_ATTR =3D "^(?:" + "|".join(VAR_ATTRIBS) + ")?" =20 - sub_prefixes =3D [ - (KernRe(r"__read_mostly"), ""), - (KernRe(r"__ro_after_init"), ""), - (KernRe(r"(?://.*)$"), ""), - (KernRe(r"(?:/\*.*\*/)"), ""), - (KernRe(r";$"), ""), - (KernRe(r"=3D.*"), ""), - ] - # # Store the full prototype before modifying it # @@ -1003,7 +1006,7 @@ class KernelDoc: # Drop comments and macros to have a pure C prototype # if not declaration_name: - for r, sub in sub_prefixes: + for r, sub in var_xforms: proto =3D r.sub(sub, proto) =20 proto =3D proto.rstrip() --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 102F3357725; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=GGOGEtWHz3j84JO5009ctcd4OrTWQtjru4Be5RQI5NO7/hDCUULYAD9gFzWM+k2eweXuNHrV3QBCPNGL0uR5YX6ii9+fYyQ9McoQgQ3o5avBhzC/Mfoy5XSKWEFp5BFJsw7xJFvpM/S+JlNZol+8jlzjqK+UIsfQJlwoaxS2TyY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=k65ZRQ6nCC0QeSNdRmqS6WoUNEEbl9/G3ipKWB3BcN0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=r4Lf6TT2QnsRAXYTwt0f19YnGv/1j+xScTDBf35Bd9HloiuY835q6e3gPzuub6DB+2TlzUlggBSc7sqaa6qCgQetkJ7xH+d/sab+3X9KOO0ft0uXM7Ir3tQA3EWGYY1cP+rqbwKHmTb/94ab+54vhtQ+nPQSTpKayAK4wCmXPNA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=e63fBHEI; 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="e63fBHEI" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6BB10C2BC87; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=k65ZRQ6nCC0QeSNdRmqS6WoUNEEbl9/G3ipKWB3BcN0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=e63fBHEIkHV7gUbvSu0y+j59kfsYS+U2rp5MWNYp5NQ0g0JUfdEhh8zX9FFM/Kobt /ihVs21vbRRyz69Q6p6+ahKpCiLT+GoqoAMnyBqQvjdGpLpbW1DwlHmRa4W1zbtY5Q i9F1iQnfMkB9haZzKgJ3rwc+tQKXFlGksj9GPaw9N84mw2IdQKLAuONYFDmInekn3x 7f+7ujrpGZ8s2YBbjnNQFTS+qegSmz1cSeOCs0zaTLhGCg1sTbDlLHDvAor/RWFO4q TprFa23N2XVs5qdpJER1yKLNqsWaWlHrqCLnmmM1h+3VfscA2EI5nVO6WUJM9EgsRn sI6nVx08tDgDg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVk0-1jqe; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 04/41] docs: kdoc_parser: don't mangle with function defines Date: Sat, 31 Jan 2026 15:24:38 +0100 Message-ID: <40010f8fa7275d1be1287b26ac46fcd3c88e2b99.1769867953.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Mangling with #defines is not nice, as we may end removing the macro names, preventing several macros from being properly documented. Also, on defines, we have something like: #define foo(a1, a2, a3, ...) \ /* some real implementation */ The prototype part (first line on this example) won't contain any macros, so no need to apply any regexes on it. With that, move the apply_transforms() logic to ensure that it will be called only on functions. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 0b68b140cd02..3ba2cda2487a 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -163,7 +163,7 @@ struct_nested_prefixes =3D [ # # Transforms for function prototypes # -function_xforms =3D [ +function_xforms =3D [ (KernRe(r"^static +"), ""), (KernRe(r"^extern +"), ""), (KernRe(r"^asmlinkage +"), ""), @@ -1065,10 +1065,7 @@ class KernelDoc: found =3D func_macro =3D False return_type =3D '' decl_type =3D 'function' - # - # Apply the initial transformations. - # - prototype =3D apply_transforms(function_xforms, prototype) + # # If we have a macro, remove the "#define" at the front. # @@ -1087,6 +1084,11 @@ class KernelDoc: declaration_name =3D r.group(1) func_macro =3D True found =3D True + else: + # + # Apply the initial transformations. + # + prototype =3D apply_transforms(function_xforms, prototype) =20 # Yes, this truly is vile. We are looking for: # 1. Return type (may be nothing if we're looking at a macro) --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 1490E357735; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=Ahfmxdvjz5En2UcrgU/X+u4vWDSsrT+Sj4uoG8Kyi/G1M6rCjtIhA5RWQTvuJu2JIoF7eiAIbx30DjNZe2M+7S1jATGUv2rwk6R/Zk/WdDx2JsEypNeD2mOAFkAxNbvVRfOpzwmO4LAAcoMBXibqXVycJMRZF3dtg1bLsUDqzkM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=V32t6uLUsEQqW7vNUksHzA79JzrYmV4ZBSdrs4RvwEY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=o9ESJTyZ5UAwqMW7WOEh6GCuUcGs0DAJ6xoTM0c6NHgGcubw56tDEdtm1gNewc9OwoRkDetuVz0mprOEdg77EIrvOd0XpvlJ3Y8t6NsVlPvzstUU/97qYGBtCOej0ol6HcBkXDHw2PaiV402uOujpOPXrhQIaIcy2AihR6uMTPY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=twPIeT4R; 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="twPIeT4R" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7C010C2BCB5; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=V32t6uLUsEQqW7vNUksHzA79JzrYmV4ZBSdrs4RvwEY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=twPIeT4Rza2Xt2SsVtRnszHcVtnu6rcM6vlPHqYmtRoo4W4fhwWMkFJ8/Thd8Wpg8 Jj6dWe3H7UWul3858QpmKj8oj5KNQK7DaXx5xulHCbn73xHTqez/j86dsA0C9Augn6 EXWBdzo2ibtS4r/78SLMsOXD85EIUMxy2mDuR6rDnI09XAXF9Vyqknp6axIAYzizeV HgpBgxTMnNhyBigDautwd3nCBNwU0XeNIup6NP9GUjYCneezJGkTvMdqO8/tu4eYz0 a5wWphteWVRXNj+v3vq8g2UGOnA1lx7Bge5lTxi9H1P6uxdiRzUyXRm1G+rhWe18bd fAWS1TsIu3eQA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVk4-1r1L; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 05/41] docs: kdoc_parser: add functions support for NestedMatch Date: Sat, 31 Jan 2026 15:24:39 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Some annotations macros may have nested parenthesis, causing normal regex parsing to fail. Extend apply_transforms to also use NestedMatch and add support for nested functions. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 38 ++++++++++++++++++---------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 3ba2cda2487a..ae5b2ef80f75 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -152,7 +152,7 @@ struct_xforms =3D [ (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re= .S), r'__u32 \1'), ] # -# Regexes here are guaranteed to have the end delimiter matching +# Struct regexes here are guaranteed to have the end delimiter matching # the start delimiter. Yet, right now, only one replace group # is allowed. # @@ -160,6 +160,13 @@ struct_nested_prefixes =3D [ (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), ] =20 +# +# Function Regexes here are guaranteed to have the end delimiter matching +# the start delimiter. +# +function_nested_prefixes =3D [ +] + # # Transforms for function prototypes # @@ -207,13 +214,6 @@ var_xforms =3D [ # Ancillary functions # =20 -def apply_transforms(xforms, text): - """ - Apply a set of transforms to a block of text. - """ - for search, subst in xforms: - text =3D search.sub(subst, text) - return text =20 multi_space =3D KernRe(r'\s\s+') def trim_whitespace(s): @@ -408,6 +408,8 @@ class KernelDoc: # Place all potential outputs into an array self.entries =3D [] =20 + self.nested =3D NestedMatch() + # # We need Python 3.7 for its "dicts remember the insertion # order" guarantee @@ -505,6 +507,16 @@ class KernelDoc: # State flags self.state =3D state.NORMAL =20 + def apply_transforms(self, regex_xforms, nested_xforms, text): + """Apply a set of transforms to a block of text.""" + for search, subst in regex_xforms: + text =3D search.sub(subst, text) + + for search, sub in nested_xforms: + text =3D self.nested.sub(search, sub, text) + + return text.strip() + def push_parameter(self, ln, decl_type, param, dtype, org_arg, declaration_name): """ @@ -881,11 +893,9 @@ class KernelDoc: # Go through the list of members applying all of our transformatio= ns. # members =3D trim_private_members(members) - members =3D apply_transforms(struct_xforms, members) + members =3D self.apply_transforms(struct_xforms, struct_nested_pre= fixes, + members) =20 - nested =3D NestedMatch() - for search, sub in struct_nested_prefixes: - members =3D nested.sub(search, sub, members) # # Deal with embedded struct and union members, and drop enums enti= rely. # @@ -1088,7 +1098,9 @@ class KernelDoc: # # Apply the initial transformations. # - prototype =3D apply_transforms(function_xforms, prototype) + prototype =3D self.apply_transforms(function_xforms, + function_nested_prefixes, + prototype) =20 # Yes, this truly is vile. We are looking for: # 1. Return type (may be nothing if we're looking at a macro) --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 C7097354ACF; Sat, 31 Jan 2026 14:25: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=1769869521; cv=none; b=l9v+CoL7HAOtRA5+lzqYxWePQH/C0WivyNW47XAOJycPYejlrkaFdSPZBoImmmCo/hwOJivJ0nJiQG6nMP+wyRipvV806/SMqoPEThVN4j14uuwP1cKmllsQXMNrhlU9JsQL31htbUidwJo6OHIxWkZc1KxpiwMQF92BpqdleHY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869521; c=relaxed/simple; bh=SI0OuhHT6kvx7zPg3IIsJPCvtLTTLub7sg5GnAeFE/g=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=nxslsWczOJDQ5s0KRUQP1a3WEzr8I2CqNsfw/k54gSUPwoggKX0AlnrxtCzNHPFPWhwibTLAY92wnSjIMnaJJaP68e6BlUEviUDaW6d0eyf9LE4NmUMIt4IixqbJ4FmUmkXTwG32RJVGhjCA+H23dH6ckWZvHjGMawNuhP9QjCA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Xo/3Vt23; 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="Xo/3Vt23" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 642CEC16AAE; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=SI0OuhHT6kvx7zPg3IIsJPCvtLTTLub7sg5GnAeFE/g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Xo/3Vt23C7chjuZ7k/WMNAMPjI5tDrGE7fZP0881O6poSzzKpdAOGgMXFZkaKBcOi no/HeR0CPK5DIDvj3lJWubQwPmmVIw8DwxCavnGH5IzOrbP8WJUXLGjcB1KfG1NlgA PJ4m93OsS0puDcKLOQnP3XRvIRAPCFGTlprCq+vFHzSoLKdnW9Xj0MP9LtTnWAH7+Q pN7VlDM/8lqPDYESZtNBvPTh0ksLTf73qARHwjoy9LFFEY+K5IB+ztfVpcjxvr0a4n 83vHXEwItfBnH8rSEXV+QyUi0wquTHG83DNa5ipLR1fEgeFbb+7emItvvl4KDEaRMF EPMj34EU7ssnw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVk8-1yFJ; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 06/41] docs: kdoc_parser: use NestedMatch to handle __attribute__ on functions Date: Sat, 31 Jan 2026 15:24:40 +0100 Message-ID: <7efbd500b098b45d697beb769f07d471c33a7117.1769867953.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 ae5b2ef80f75..64165d8df84e 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -165,6 +165,7 @@ struct_nested_prefixes =3D [ # the start delimiter. # function_nested_prefixes =3D [ + (re.compile(r"__attribute__\s*\("), ""), ] =20 # @@ -195,7 +196,6 @@ function_xforms =3D [ (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2= "), (KernRe(r"__attribute_const__ +"), ""), - (KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+")= , ""), ] =20 # --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 D1357356A00; Sat, 31 Jan 2026 14:25: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=1769869521; cv=none; b=t7c3MLiknzwlBCpxQ1IcKqgz7NfDIK9ZhWCJ89xqBoA/qhO3Gtks+8oNQkAVQhUysxNyqpRxnG8rEG/P2S3RQUgExqcEN/FtQ1ptj2SPNm+OeWbXFZZ4I12dZfjf+jskHH2NvFb5nQjUGkXvcvr06lrCGlNrqDQXvoWd+y2/aUY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869521; c=relaxed/simple; bh=R+lEuWZm4gs2UH9ywluoEBP8XgG1POTA/3QmMS82aUQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ii3zGKKSDzv46Kv9mphMFrwadHaNP72DhNOOzFG3rSnRxqzjcI6URUeDQGfYDnBkcSX6YrSDXo4xZZvbBnABUwp1gcVkh9M0Z5dtJM85l9U9O5dFojo5KvTbnHyNRX2chy464Dj4EbjF7daAYJxhiGNWvU9orPkn3nexRtsVKcE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=OmO+GkNQ; 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="OmO+GkNQ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 69352C2BC86; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=R+lEuWZm4gs2UH9ywluoEBP8XgG1POTA/3QmMS82aUQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=OmO+GkNQzROY8UXEsWbQLH8djRLsR2ixEWp38CBXq2MQh2bZrGNnJz+AbNxiccXgJ 3JfJ1SeiGr75ZTTyy+kxsaiMfLzTs+zwT/ThdvgrReLNY2jblj+Fl0XkAA6v+2iJZs St6cPOotJLMvFoqYo59i27hTqbomG48wsJti7IHB25erya+EIzAhxKW3BgeG/QdKo1 du6tXS0i/ewyyRFzVScbPugMkbgAM+zcPdAvUCXTDLMz7RLT8A7JdpL38FjT2Mv6N4 U75omrjw3QdTrXTPq/8R6RF42rVmMv4/7QDEB2bNI+1Xw1nCJA1ly+UWAJn7+88XOz wXG7LY2MbV5FQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVkC-25QF; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 07/41] docs: kdoc_parser: fix variable regexes to work with size_t Date: Sat, 31 Jan 2026 15:24:41 +0100 Message-ID: <58131226492f1a0f369fa8e4143535b972d77aa6.1769867953.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The regular expressions meant to pick variable types are too naive: they forgot that the type word may contain underlines. Co-developed-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 64165d8df84e..201c4f7298d7 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1027,14 +1027,14 @@ class KernelDoc: =20 default_val =3D None =20 - r=3D KernRe(OPTIONAL_VAR_ATTR + r"\w.*\s+(?:\*+)?([\w_]+)\s*[\d\]\= []*\s*(=3D.*)?") + r=3D KernRe(OPTIONAL_VAR_ATTR + r"[\w_]*\s+(?:\*+)?([\w_]+)\s*[\d\= ]\[]*\s*(=3D.*)?") if r.match(proto): if not declaration_name: declaration_name =3D r.group(1) =20 default_val =3D r.group(2) else: - r=3D KernRe(OPTIONAL_VAR_ATTR + r"(?:\w.*)?\s+(?:\*+)?(?:[\w_]= +)\s*[\d\]\[]*\s*(=3D.*)?") + r=3D KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_]*)?\s+(?:\*+)?(?:[\w= _]+)\s*[\d\]\[]*\s*(=3D.*)?") if r.match(proto): default_val =3D r.group(1) =20 --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 1354D357727; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=NQKT00MXFVS0nx2xbg9SPGwEXJSIkLk8v+KprmqGkBchHQoGBIk9gsUKe/YyHvRBaA2uOA6I/L/4N0ZPluVUDWveDSfaXPkD45TMFHisJlYF+uL6NGxcx0gv254+Q44mQE+8JKxUzxe/N56jDe8LnKH6PTlXKZU3lJdGTve03pw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=yw3wjIPht+uMyxqsB9EmBpUiGx/X/g23mgLbGJyQImE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=TjirLgvoVbhMZlAWNavGH9uKhMx932B/HBf8tBC7G+2w2mkPEy/F/1gfb9+eb73cvRhH97beb+k4hiAEio1b7BS5R0tDmb4UUh3LrxbcIH3uzUz5o5YnMIfBFe0ZuptpfbUeqsGZ177ReZ0uredlqwJIz/3fYneyzPx16+ow+nY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=N5Z/gI9w; 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="N5Z/gI9w" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 77B32C2BCB1; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=yw3wjIPht+uMyxqsB9EmBpUiGx/X/g23mgLbGJyQImE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=N5Z/gI9w/dNIrHboFLisXZawZdYJCm74VxVYg4w4q1Qu+fC83gC/W5pOlE1WF8mmK ruledqO1vY8jYQNRLqljrSHXzoB/DSmYLlYMejuDtnfe7m5bUH6a+f9VGzI3X0UwPD 70+jmg6i9sptleGFqnibQMLYIEF0qYgExkLZPhQO8I9Kf51M64EvwR6dKq72MTZ6On Mbmwi9Stftnvj4QIdc7/vyKqL6i0YMcYAqxOuG1a8HXUjNHp4YQcp0G+5G/WextMQl V2cSk/2g8Bp0Vm4oxKfKFL5E1P1ClhC1+Budz777dsY66KjWT666oVadQoAtpmbqcS iskgN3KPz/FkA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVkG-2Cuu; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 08/41] docs: kdoc_parser: fix the default_value logic for variables Date: Sat, 31 Jan 2026 15:24:42 +0100 Message-ID: <2940b90b1ce4b63af2ac813404512c62cfb505f0.1769867953.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The indentation is wrong for the second regex, which causes problems on variables with defaults. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 201c4f7298d7..cbfdaba39494 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1035,9 +1035,9 @@ class KernelDoc: default_val =3D r.group(2) else: r=3D KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_]*)?\s+(?:\*+)?(?:[\w= _]+)\s*[\d\]\[]*\s*(=3D.*)?") - if r.match(proto): - default_val =3D r.group(1) =20 + if r.match(proto): + default_val =3D r.group(1) if not declaration_name: self.emit_msg(ln,f"{proto}: can't parse variable") return --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 C71143563FF; Sat, 31 Jan 2026 14:25: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=1769869521; cv=none; b=QVqfnXvuz8yIaL/biFKzoL2ZTT9ahrAu4oUxpJDbo3Ycc48M17L5KNG3D/9FhaRbX5G6V+LOPLTDWMgrKT0TXSLMSi9gpr8Yh0+gtkjslCtNS2lozyZxm6/ezs4YdDJERLE+GML9yAxpajQrnTQ44xovLV2Gu8rlplu/8p6CV/A= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869521; c=relaxed/simple; bh=jWm+CmUFkxoOutvSyo+VT0i3ZnquT0lXIxHybrc0xCk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Np0Ud9z0vCVL/Gu/SlUtsakMyEb4HzjQea/d9hLjddk8Il8NtSIhvhHkxhpp4h7l7pRO7XJ01hAkvIEniBXJyCl0MwYAp7QbN1Gq62gXatkK5mOhim6fDFlGLtMSY41rXqtsAdu9OCtUxCMmSYKTJnQFQdyYa/Ha1y3uI5ILytM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=atoMH831; 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="atoMH831" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5D5DEC4CEF1; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=jWm+CmUFkxoOutvSyo+VT0i3ZnquT0lXIxHybrc0xCk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=atoMH831TdPUZHcjP/q4dYY6e2+IqK4edHjH2ZRrVXlZggeRNTRPCog3oTqIedFdg mDj4doz0Iv2A8YixwYzdXWmMP40a9X6i5sQk9NxOFrQ5LX/8o6eb8FnrLjhCzonpFQ kSghVv5EnmlEGGyBqvgSxpi3SGPF7MCrL4dl7OQAwzwb2S++G6V7/9sBvt5LsM+fKC y0gd/npr001YUPZHMKaiGKBqx5LBTbah+at/heqTuVnv4wtBl9ba31vnbE72WZmFML 2FVvNSdaFjKDXhD/gJmu526yEByb4HOuV5GW0t4aEAEBWfgWU6YFjTY5xBhajSczYE i0ODuqJQXaovg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVkK-2K4i; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 09/41] docs: kdoc_parser: add some debug for variable parsing Date: Sat, 31 Jan 2026 15:24: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 This is a new parser that we're still fine-tuning. Add some extra debug messages to help addressing issues over there. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index cbfdaba39494..ccee4e0bcaab 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1033,11 +1033,19 @@ class KernelDoc: declaration_name =3D r.group(1) =20 default_val =3D r.group(2) + + self.config.log.debug("Variable proto parser: %s from '%s'", + r.groups(), proto) + else: r=3D KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_]*)?\s+(?:\*+)?(?:[\w= _]+)\s*[\d\]\[]*\s*(=3D.*)?") =20 if r.match(proto): default_val =3D r.group(1) + + if default_val: + self.config.log.debug("default: '%s'", default_val) + if not declaration_name: self.emit_msg(ln,f"{proto}: can't parse variable") return @@ -1045,6 +1053,9 @@ class KernelDoc: if default_val: default_val =3D default_val.lstrip("=3D").strip() =20 + self.config.log.debug("'%s' variable prototype: '%s', default: %s", + declaration_name, proto, default_val) + self.output_declaration("var", declaration_name, full_proto=3Dfull_proto, default_val=3Ddefault_val, --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 C6F5F354AC6; Sat, 31 Jan 2026 14:25: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=1769869521; cv=none; b=AWOTvaxbeY8i9D8Utf3daKbiPSDxwm6WhrfD1LQZGKX+knFB5hW5bvLvRRLMe3OHc28xfyphu7HqfwjE/bi6FIiE+cmWqPpK5H2zN8b+3lub+Eh6Z6kOMwpklQZ50QWCKVe7seyuKl6giP0ryaCyAj9IlqtgBB+R0OcM+KbwGsQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869521; c=relaxed/simple; bh=QZmQg75J0lv0h13oBHLpIAAeXL/qqKinXYAYwI6HMj0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Fal1e6SMdD8m0zL2kQT9a9SDB/NIHImpJkVfOOggjdVEYooEBqNAvk+IV7nrz6ewoQVrVF8A9bbnB2FDgz0nQqJzKslAtMFLLXns3qWT6Wv2uwiXVTzjeNT5OiVGNY5fk1Znu8y8BVpv/vlI7nH/IgdQrD7V8xSchowQwy9X6tE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Sb52ZuNd; 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="Sb52ZuNd" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 61E05C19422; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=QZmQg75J0lv0h13oBHLpIAAeXL/qqKinXYAYwI6HMj0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Sb52ZuNdHSAwnw9jy/Z/wDHDrcVla27f/hRVnMlGy/aibPbxaldBrAqR2uYMLC2v8 ZQ0WlxPuXkkhFzv58wNqN28fh+RXHqX/pIAkOBwAiK/LdMBfTuIE0OaVjCxWk0M1Mc inzeV2TvC9xmm2wt1Ddh8FLWgQ3yfPlfO87QJVYnk2PdWGQ8Sld5tjtokXTi4E6rm+ RTaxpbtpnKS2T5qcfzCvX5SqLQlY7w0OlBKm5gBvPvGPX/syJnbMCMiMmfg7GrMy/1 pBz+M5ZZIFlvX1iK+GNNIeQYa6Dncl1XHhs8UwvnzDiEqjYLMB5aJ54SmUUaARt44B uE4n8/2GxRguA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVkO-2RA7; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 10/41] docs: kdoc_parser: don't exclude defaults from prototype Date: Sat, 31 Jan 2026 15:24:44 +0100 Message-ID: <1d202b0774652e5b7258b50735955da6948dc633.1769867953.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab If we do that, the defaults won't be parsed. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 1 - 1 file changed, 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index ccee4e0bcaab..0b6cba442d72 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -207,7 +207,6 @@ var_xforms =3D [ (KernRe(r"(?://.*)$"), ""), (KernRe(r"(?:/\*.*\*/)"), ""), (KernRe(r";$"), ""), - (KernRe(r"=3D.*"), ""), ] =20 # --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 1681A357A20; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=G2HMvXho3JYfmYO4AGA5hN0LG2WAnsUcKlSAEKVJQs8o2h8eD8C3yA6HIB/BL4jF9W+uSaATPdhK/kZ3pAcXKlb/i9v1ytYBhkLHG9sNeY+zTQm2usaJDGoxA+KS7QmCmGP/1SQACJTsSALmbydi2d/ponFAk0w+zgnakT8gkFY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=aiHLIfS5F+miX7dW9x3ionw6eHjNQsSUUYhH3F5IK/s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=dgcI4ixYV9DCuI5GCdsSjaCnF1LGwY5/cF6Sbe3mKBKnZEkU+YJxRgAwJjWANby5XB3P8ZzinQ9UQCynzS8nJZ3z72z7BR5QFBGqwiUAYbG9ztkT/soXD+0rRDp3SaLYJh+0bSSIMQf29jGml+Q6nJOx3hVW7c+5qnbeNKctAKY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=GZ8ffB0o; 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="GZ8ffB0o" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7B123C2BCB2; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=aiHLIfS5F+miX7dW9x3ionw6eHjNQsSUUYhH3F5IK/s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GZ8ffB0okAa/JZq9EY0ksEvsodBd6UavOLLuUMYwJGch0xaJ5NzYy/XmzPvHPCo3q RqSaKMODYYaWzPYPITpqTiZ4yCGBhA0Hqk0xQYThuoP3/dzmCL9UShHBcj9vbLKvXk 5iYtPT8ML/OhYwkWrBTnCoRX14C8GyC0dy4WHAaf2dj5JS8NnxttcDA2fqoZ8+Qdec 9pp7YED0qK5vhb7GtLxFuNVzNwefL1IxAyM3xMdf0X3e2Bo7Suzfbz4hi0xetRN8TL 1VHVBEenAyQxB8YZ8M0U7zBdg2/K4wZpYEhp7J2WPpk3U60jnUMJVi2JX2ltmfVDss pqkDmdp3yNW+w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVkS-2YEf; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 11/41] docs: kdoc_parser: fix parser to support multi-word types Date: Sat, 31 Jan 2026 15:24: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 regular expression currently expects a single word for the type, but it may be something like "struct foo". Add support for it. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 0b6cba442d72..21cc4e19a1e8 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -1026,7 +1026,7 @@ class KernelDoc: =20 default_val =3D None =20 - r=3D KernRe(OPTIONAL_VAR_ATTR + r"[\w_]*\s+(?:\*+)?([\w_]+)\s*[\d\= ]\[]*\s*(=3D.*)?") + r=3D KernRe(OPTIONAL_VAR_ATTR + r"\s*[\w_\s]*\s+(?:\*+)?([\w_]+)\s= *[\d\]\[]*\s*(=3D.*)?") if r.match(proto): if not declaration_name: declaration_name =3D r.group(1) @@ -1037,7 +1037,7 @@ class KernelDoc: r.groups(), proto) =20 else: - r=3D KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_]*)?\s+(?:\*+)?(?:[\w= _]+)\s*[\d\]\[]*\s*(=3D.*)?") + r=3D KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_\s]*)?\s+(?:\*+)?(?:[= \w_]+)\s*[\d\]\[]*\s*(=3D.*)?") =20 if r.match(proto): default_val =3D r.group(1) --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 055D0357711; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=CDAFB32cl24ddX+2/XegV7NB/FuOhIZpt4HW+HsS0/krwK3obieJTIpEgHdDQi9hee6+fmFlo3KqZlbCd57g+nn/W6OKKpXBFmSGHhhb0t7oV2NQLyGrV1d1XAazy7J2XCrWVWQiFwCtKkLFlLPIB3ztnVXAQaVxgaJ+qWLSQgI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=uOq+nl7eJthPvVG9hgcDgM2eUmvJY3Ts+Jdl+DSpsYI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=TgP/iHFH72JujyJKggJ+9iJucNIFJOhVkru1B8B4oybBMUR1NwGmhjDtsiI6fUQ6Lc57Tk+0VdTwUaKFiIKhEJfaNC7IdDi+u3Z8XKg1MiEclKr9eOniCS2IugdcRtEkEk8nPBPlOsyANrlpcKVe0P6RuklxiaouOZXu+5nFj/I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=neOACnZT; 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="neOACnZT" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 71CABC2BCAF; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=uOq+nl7eJthPvVG9hgcDgM2eUmvJY3Ts+Jdl+DSpsYI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=neOACnZTJdN4hBjqEVf5dn93zlY5Ke3dCNR50AducSB2fWBw/1/3YKlYFd8Nx66S2 PklvVqDS/z4xvv/8X6Wr+gQhcFgKEtYKyyuHIwRN0z8+3gQ1XEyPwlGZ8AJmwgNsmx qhY2MCJQ1T4dmkDUOm3SuanelIuDfqLQkBcdufrLnbdK5dF271OT+L9iN3qtE9BWeT dGsRFsDy4mXqeldzejd3nBHO1vKh4jIE+8Zd9WVsJBChrEW4E4YEMiyELWJxV+/Kwk d02ZYDhtL+hqo8nm/HajufmJdYPdqDF4/oh1zcuXp3bVB1VjvOnGO5Gbewsn8T3U0W NRuAPxDuPxRwA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVkW-2fUw; Sat, 31 Jan 2026 15:25:19 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Randy Dunlap , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Mauro Carvalho Chehab , Stephen Rothwell , Mauro Carvalho Chehab Subject: [PATCH v4 12/41] docs: kdoc_parser: ignore context analysis and lock attributes Date: Sat, 31 Jan 2026 15:24:46 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab From: Randy Dunlap Drop all context analysis and lock (tracking) attributes to avoid kernel-doc warnings. Documentation/core-api/kref:328: ../include/linux/kref.h:72: WARNING: Inval= id C declaration: Expected end of definition. [error at 96] int kref_put_mutex (struct kref *kref, void (*release)(struct kref *kref)= , struct mutex *mutex) __cond_acquires(true# mutex) -------------------------------------------------------------------------= -----------------------^ Documentation/core-api/kref:328: ../include/linux/kref.h:94: WARNING: Inval= id C declaration: Expected end of definition. [error at 92] int kref_put_lock (struct kref *kref, void (*release)(struct kref *kref),= spinlock_t *lock) __cond_acquires(true# lock) -------------------------------------------------------------------------= -------------------^ The regex is suggested by Mauro; mine was too greedy. Thanks. Updated context analysis and lock macros list provided by PeterZ. Thanks. Reported-by: Stephen Rothwell Closes: https://lore.kernel.org/all/20260107161548.45530e1c@canb.auug.org.a= u/ Signed-off-by: Randy Dunlap Reviewed-by: Mauro Carvalho Chehab 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 21cc4e19a1e8..92b550189988 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -81,6 +81,8 @@ struct_xforms =3D [ (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ' '), + (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ' '), (KernRe(r'\s*__packed\s*', re.S), ' '), (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), (KernRe(r'\s*__private', re.S), ' '), @@ -165,6 +167,16 @@ struct_nested_prefixes =3D [ # the start delimiter. # function_nested_prefixes =3D [ + (re.compile(r"__cond_acquires\s*\("), ""), + (re.compile(r"__cond_releases\s*\("), ""), + (re.compile(r"__acquires\s*\("), ""), + (re.compile(r"__releases\s*\("), ""), + (re.compile(r"__must_hold\s*\("), ""), + (re.compile(r"__must_not_hold\s*\("), ""), + (re.compile(r"__must_hold_shared\s*\("), ""), + (re.compile(r"__cond_acquires_shared\s*\("), ""), + (re.compile(r"__acquires_shared\s*\("), ""), + (re.compile(r"__releases_shared\s*\("), ""), (re.compile(r"__attribute__\s*\("), ""), ] =20 @@ -195,6 +207,7 @@ function_xforms =3D [ (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""), (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2= "), + (KernRe(r"__no_context_analysis\s*"), ""), (KernRe(r"__attribute_const__ +"), ""), ] =20 @@ -204,6 +217,8 @@ function_xforms =3D [ var_xforms =3D [ (KernRe(r"__read_mostly"), ""), (KernRe(r"__ro_after_init"), ""), + (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ""), + (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ""), (KernRe(r"(?://.*)$"), ""), (KernRe(r"(?:/\*.*\*/)"), ""), (KernRe(r";$"), ""), --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 2152D357A59; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=FkGPDD3DHY87NnLbIJy58fV9Q/mXti1XXDzpPM4HUzjeDpSuMazy+Mo8pMINKc4ODmhH8cRniJsUz1Wf801banMiokXK9jsnBaUCVUbcZhSvHI1zI8nzf0Ycou9jLeQFYX6y4jICcOBjemNhO3xFJjO5eitPY5bbBJuAjm/fLBI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=E4fJO9wVUnaqUlAi5WmkzEmXnpOij75g8JwiGBZaJ9Q=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=AXX4PDFQXRYrntxhf2QXNS9ZXpQQMNhbfqKCDzb6pwtYV4LfMxoKwtaG5HyRjNLAhF7zbau1sHDGFOCdKbQTn+uE+KadmmLEhOqSGJwSB+qS1eZixY9vN2sYd82axbtiGv0vto4t8Y2E/uTL0Hgl8/RPj7UEi80Qiq4ZvyEDFtU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=T3JUosEF; 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="T3JUosEF" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7FEB9C2BCB7; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=E4fJO9wVUnaqUlAi5WmkzEmXnpOij75g8JwiGBZaJ9Q=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=T3JUosEFJJEjm57nIN5CeAd93uZO4+2EAFKhDcuIbkebO1FR7POhOcbcWgZueyjxz /IXGruDaiYAZz5IDDMkSzYsse7MozmnPNwyYQ8YggFCXDpNaPTh0vTGS/jP152zC7j czzMbvpxWdlmG/CBEtjZDH+Jxejj1xUlPWmhmsAvgpBeAjSfrsEp6at4bEQGHheS0p 2Pd6103t7cEK0kCjoXibs2v9jbZ0I009Vab8mMb4bm3yMhx7jMcI1E/PLCPjN2dVXw nj/EAPU4U/6kUE05hcZ18vsYp8a1GBMvr+2v2XPhxvic6Epx9QexnaN5o3IjvqpgNq mqUN574QnMeEA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVka-2msr; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 13/41] docs: kdoc_parser: add support for LIST_HEAD Date: Sat, 31 Jan 2026 15:24: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 Convert LIST_HEAD into struct list_head when handling its prototype. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 92b550189988..33710c4be145 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -219,6 +219,7 @@ var_xforms =3D [ (KernRe(r"__ro_after_init"), ""), (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ""), (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ""), + (KernRe(r"LIST_HEAD\(([\w_]+)\)"), r"struct list_head \1"), (KernRe(r"(?://.*)$"), ""), (KernRe(r"(?:/\*.*\*/)"), ""), (KernRe(r";$"), ""), --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 1FE8E357A57; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=RAItewXA07fmNdzE8s9NN7wtHLhhE+gtb1G/TH/nFluhzccuzrc6wR4FZNhM77dZ04oViKzOqfnOedJeyu5o2Sm0kYt/8k2rlHGPsLBUbe1H5vSoJbui6unojE8PsBFmT0x+M2FyH5AOctrk7Ts8Hohd2t+l+48WghIRRimw6f4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=enNjosNVgnaAAD5QxgjX5hIH+/xBNCW9H6F1I/JJjkg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ad209YuqawAYXorB9+kdVbExIgSgMCpJ/4QqoXo8l2p+psaaOaaxposy3adWlZh38eEZU/VBndxQrAcIsmYU0wi8M/eL0R+YlU1uCuHauLuaoIKneZFNg9guLaDX+WB7/1BysODKeftW2yLbNAc7IbNpS3PviYGkX+erPC2s9bE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=SPGW8Q5W; 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="SPGW8Q5W" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8792AC2BCC7; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=enNjosNVgnaAAD5QxgjX5hIH+/xBNCW9H6F1I/JJjkg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=SPGW8Q5Wj/Kpohrb03QakzQo7UlPpS/JZKe0yv4eUfMVholL6LBI4JI+/3DkpEb/B yhVYJhmiivl2WHinw/H/5jh6QwlTYUhx1PBdDk8WxTZRAJ8FPv6PaBCk1CjSnfy1/g wMmoUxVODTqrSv5fi25JceOe5ieQ0HkwkQtqUcObQK1W6qtwqkIh6vwsvW4tly96vl OPtCN3p/zvLxPZDjVkt93mM5FpvkGlj6pKv33GSa3db10OsK05T+hGYO/6KIAZ5AaB xT+4D99cf1PbK4Dkw/90DGEhtUDEOTjYsJT5tcThKXvocoKJPEmy3+k+Nio52kUDIX gGzdwWOhgCsdA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVke-2uFV; Sat, 31 Jan 2026 15:25:19 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Randy Dunlap , intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Aleksandr Loktionov , Mauro Carvalho Chehab , Mauro Carvalho Chehab Subject: [PATCH v4 14/41] docs: kdoc_parser: handle struct member macro VIRTIO_DECLARE_FEATURES(name) Date: Sat, 31 Jan 2026 15:24: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 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 33710c4be145..db140363104a 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -152,6 +152,7 @@ struct_xforms =3D [ struct_args_pattern + r'\)', re.S), r'\1 \2[]'), (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', r= e.S), r'dma_addr_t \1'), (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re= .S), r'__u32 \1'), + (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1; u64= \1_array[VIRTIO_FEATURES_U64S]; }'), ] # # Struct regexes here are guaranteed to have the end delimiter matching --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 3779D358D08; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=jl8SjJC7aAai59NABPdreXn2Qwd93idhiZkzvwgrU/JCk9a9Uo9SwbNK/PpFxU/jcPABz/0Ec9y77pKRfngp9Iw94v+2eMK04R+2sTx2Ue+SmgxbkAky0Ztt8LfYc9HI4xTpF+0+xIhWY7JuB/V+2XurmeMAsGMu/KCzJ1VzJiE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=T/tjtljgzM6ONqM7zhOV7Yk4y75K/wRjyLKxDsGKFtU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=YJggXgVQs1plvs7oZ4TEsdQBgYltfbWYGsMyENw+0mYGczcnoekikwO1MDqMSV9BoTaUhT7jxP3N3MKBfbOE+zMcw8H7m5K8Wzu0AIZi0rAlpDLmG8geabjM6eJPHiHccONA5wZyWotav79Y9TXIvS04utBY4dg6Fnh8bdEpXRM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=FkI80vV6; 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="FkI80vV6" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 86E28C4AF0B; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=T/tjtljgzM6ONqM7zhOV7Yk4y75K/wRjyLKxDsGKFtU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FkI80vV6n8l3oW8lP1wSbfB0XPQ8C7wAan32GnKk0HvATwLICSCBRX2x6QZ/ajzb+ Ty5boZfyRuzsQg+Y9QsgOtZuDo4SUQr5lWk4jjwgPg7sc4Yav4O2DQJ9iZJgZRapyk E5ybY6Y6tWdiOxZoq+qVgvQvlRKvEgzNJz4eQDcSIXQW6TG/N7AFZby0zH99zIjXPj cIbzMxpTBUBrrG+nQMWj/sSNLVW4zVVo8sKcrA/2g7VEBI6B7QSnSTLv40mVqoilIe VZoOB0MMKmay6en0IPHcwFqEkQReiNZw9dZhbf+SHLnfBetOI7e7/DCcZMYpMvEWr0 NYIjs6aVBSVBQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVki-31UN; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 15/41] docs: kdoc_re: properly handle strings and escape chars on it Date: Sat, 31 Jan 2026 15:24:49 +0100 Message-ID: <6c8e7354e4aa7042daae46b8c778c4195de10df6.1769867953.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The logic inside NestedMatch currently doesn't consider that function arguments may have chars and strings, which may eventually contain delimiters. Add logic to handle strings and escape characters on them. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index a0402c065d3a..1861799f1966 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -195,6 +195,8 @@ class NestedMatch: for match_re in regex.finditer(line): start =3D match_re.start() offset =3D match_re.end() + string_char =3D None + escape =3D False =20 d =3D line[offset - 1] if d not in self.DELIMITER_PAIRS: @@ -208,6 +210,22 @@ class NestedMatch: =20 d =3D line[pos] =20 + if escape: + escape =3D False + continue + + if string_char: + if d =3D=3D '\\': + escape =3D True + elif d =3D=3D string_char: + string_char =3D None + + continue + + if d in ('"', "'"): + string_char =3D d + continue + if d in self.DELIMITER_PAIRS: end =3D self.DELIMITER_PAIRS[d] =20 --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 2D77E3587C3; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=cIrUiTpgrt63aDcfyVob8HkEMzuTGKawiGRzwjka6Rdtl92/JzBDSDAzMDMbu1VPUbXDCERGdYD941inhuaczBxrBmv8xFXZHXdKON3krcK+r+/9UbfeNKeOMwuXDgh1nhP8T8J1+bGTCGgMQPAojuY9gbC5/3wghV8/Hjdsu0M= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=f75PYMG6ddvHOj0au37tuHra8a1RYsJ5qmzwD4SUTjA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=AbfqDGrSyjEwvJtdgeNzhXcTgTHTfU0apN5OB9zuFSLmEFp/HosC2LgNmPJOUSWDHXBjKX01t2hmgvYBLA/fQm6zTukbQCTcOk9Ji6LbSOtlcjUBGd/31S8uliPiQFe7tSz0FlpwPBhfh/wtg3h3E+niesbgcYewrBmz9WhrgGY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=f1p0q3/r; 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="f1p0q3/r" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 80AF9C2BCB8; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=f75PYMG6ddvHOj0au37tuHra8a1RYsJ5qmzwD4SUTjA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=f1p0q3/rMjMPWREONbC8rMKcph3t8I45QF2IDKfCfUrKuKcq9HvyuMUORKQSeqoSO l/62TEU6GDqm5+sXuxKGCu0LxVoCSrMoZXv2aqGSvk9sE7IJH9Tmbgk4NbnGj+4Lwh 8Ou4aS6bDve+hsKdq6rSEM7nYXRLhxTkimeNGhQ1Pni0UxA4PFIoiWWL9styvraMjs Qah5GB1BvxahKCe7e08+hwOouK12F1U8SnWGsM1NVhN3sxI7zByxNEyBojHHYbsiHv Kb9ZpHitHaOKYubFpvnmr9xVxu+qqOv27H50IN3bSXkof4Ek9bU9TQR9HS9KVQEHgs GhEdoBGmIK8BA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVkm-38lv; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 16/41] docs: kdoc_re: better show KernRe() at documentation Date: Sat, 31 Jan 2026 15:24: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 the __repr__() function is used by autodoc to document macro initialization. Add a better representation for them. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 1861799f1966..3f405addcc58 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -52,7 +52,28 @@ class KernRe: return self.regex.pattern =20 def __repr__(self): - return f're.compile("{self.regex.pattern}")' + """ + Returns a displayable version of the class init. + """ + + flag_map =3D { + re.IGNORECASE: "re.I", + re.MULTILINE: "re.M", + re.DOTALL: "re.S", + re.VERBOSE: "re.X", + } + + flags =3D [] + for flag, name in flag_map.items(): + if self.regex.flags & flag: + flags.append(name) + + flags_name =3D " | ".join(flags) + + if flags_name: + return f'KernRe("{self.regex.pattern}", {flags_name})' + else: + return f'KernRe("{self.regex.pattern}")' =20 def __add__(self, other): """ --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 341583587D5; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=fkFmbQIjLbIyIoTjTI0ItqyCXqpx9TsyN3y170zpsVhbawv2QjDPd6ajKPfpghoCJU7aA3SljM+qnijTyXDB59UlGT7f0bFd9gnnIsmqO8fkwHJ4bV00AN8nM5sJa4GaRZApm2CWrLwzLW0cpG5yOWO2ioX0caV+uLqF9YOP7Zo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=TvREth92NF6fNTFgSgL54R3ntJRc7XyPNB89X1Rad34=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=nVAYipYS9Su6yZm4jvUfIRf7DhlWyKyz/Bbw6ZD/XtyZT2G/7jDxRjgQgVFprTFdDR1mlfh3aVViE81QRWDVAdzrpHtlCnq8c98iwQYihRgnFhlchVJz9nclA2TRozocuHyucYFsOxSAXHm07NuG5nhe5k1DVeTLIsDZrGXoGmk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZVGT06xv; 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="ZVGT06xv" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8D5D7C2BCF5; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=TvREth92NF6fNTFgSgL54R3ntJRc7XyPNB89X1Rad34=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZVGT06xvbbRiRUp9pRgz47MnGGtUYKfpyk334D6YkkLqP9n7z/13PZpXKepOSVagY ya+WB7IhalWJIwJJ2dJa/qhsfPkVMFFXqX58pOh9VONul+Gv5A8QR/WrhXnoJ6SO9N WvlI07Nv+a1xUNB/i0uodehQag00waTbGC2dM2p3qN/caD9RwNCIaZb1OluaACLwGT PSckk2flxaWzfdTbDDSjjHRL3nnr2sCYYDYcRKs9b0aukQYEaju+TQY2zl7JuLFzhK ++MbPxgfKe1pBzjJfNk1i8EeBSR/GuSbSvDIkA44sqBbxuL5b3T9LPpfTRWBYdLA06 Gs6YnTwyACI9A== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVkq-3G5t; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 17/41] docs: kdoc_re: don't recompile NestedMatch regex every time Date: Sat, 31 Jan 2026 15:24:51 +0100 Message-ID: <74fae2d87073959ccf92c7c80323dbe785f0086f.1769867953.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Store delimiters and its regex-compiled version as const vars. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 35 ++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 3f405addcc58..7b7ddc50ac36 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -99,6 +99,13 @@ class KernRe: self.last_match =3D self.regex.search(string) return self.last_match =20 + def finditer(self, string): + """ + Alias to re.finditer. + """ + + return self.regex.finditer(string) + def findall(self, string): """ Alias to re.findall. @@ -134,6 +141,16 @@ class KernRe: =20 return self.last_match.groups() =20 +#: Nested delimited pairs (brackets and parenthesis) +DELIMITER_PAIRS =3D { + '{': '}', + '(': ')', + '[': ']', +} + +#: compiled delimiters +RE_DELIM =3D KernRe(r'[\{\}\[\]\(\)]') + =20 class NestedMatch: """ @@ -183,14 +200,6 @@ class NestedMatch: # # FOO(arg1, arg2, arg3) =20 - DELIMITER_PAIRS =3D { - '{': '}', - '(': ')', - '[': ']', - } - - RE_DELIM =3D re.compile(r'[\{\}\[\]\(\)]') - def _search(self, regex, line): """ Finds paired blocks for a regex that ends with a delimiter. @@ -220,13 +229,13 @@ class NestedMatch: escape =3D False =20 d =3D line[offset - 1] - if d not in self.DELIMITER_PAIRS: + if d not in DELIMITER_PAIRS: continue =20 - end =3D self.DELIMITER_PAIRS[d] + end =3D DELIMITER_PAIRS[d] stack.append(end) =20 - for match in self.RE_DELIM.finditer(line[offset:]): + for match in RE_DELIM.finditer(line[offset:]): pos =3D match.start() + offset =20 d =3D line[pos] @@ -247,8 +256,8 @@ class NestedMatch: string_char =3D d continue =20 - if d in self.DELIMITER_PAIRS: - end =3D self.DELIMITER_PAIRS[d] + if d in DELIMITER_PAIRS: + end =3D DELIMITER_PAIRS[d] =20 stack.append(end) continue --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 3CDBB358D27; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=sxmeSCqnS1O3SaQZnUr9xMVOZ+NUlg1FT4c7NTrhJKGZsofEcTzo9/HNGGdftfdkPcYYGH2TzNYnuI3DEsmKNGmGUS21m4BRpQYW/9dEc74OzgB3EaKiw2tsr9E9pfZF/9XXxiTTuKjxG9h4whTL8KdjVjWLNgfaRKUCG1Xr8P0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=iz9xyvW3XE7yzsvjnd3rhkZs9CrYswt5vPlbqVTvJig=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=sOyuvEOF03mGr/94FvyW52aqPEbMyND19V2phPgzXORuoRG7N3me6XGDaAbfHyXINs33EbPZgIiZWbauuvieTjaikTiey3ljx9bmm//7337DuZ9B/Ike0QYrE5E1p224MJadOASoerR0uDPtDjvcNOjK77LmScQK8ppvfpkCxJk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=lMa+luBP; 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="lMa+luBP" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8BAEFC2BCF4; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=iz9xyvW3XE7yzsvjnd3rhkZs9CrYswt5vPlbqVTvJig=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=lMa+luBPJ+zqyvOKQ8UuTGthfF+2TtQ/CWvwB5BZwiH5tjhj+j7tP78WOQIcjq1q3 z9utSNnb2u18xV2StNusik9UkeaQCD4/blOqo9cGO1oiAGK4SYrf0v+ZQ7hhHRUBZa Lv/RmhZbQJQkh99vGMaaLaUmfjQ+7tvF2OlvlHM1qJWIyX1JSz0UKk0ZlsyYtQSJNp 0yJ33k3qum1OVb3t1kMevOJ+Yyjp+oMKLHon7AbC+TK8MvW6Pq0gUKhO59/VSLU8GO DqcXAsYA83Ol1TmkaIZI/vWQk21uMiBE8JO2EJqWsPEd6cHO1hht0LwZ0IRCzoducH /LiW+wK0uJElQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVku-3NDi; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 18/41] docs: kdoc_re: Change NestedMath args replacement to \0 Date: Sat, 31 Jan 2026 15:24: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 Future patches will allow parsing each argument instead of the hole set. Prepare for it by changing the replace all args from \1 to \0. No functional changes. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 2 +- tools/lib/python/kdoc/kdoc_re.py | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index db140363104a..4d52a00acfad 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -160,7 +160,7 @@ struct_xforms =3D [ # is allowed. # struct_nested_prefixes =3D [ - (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), + (re.compile(r'\bSTRUCT_GROUP\('), r'\0'), ] =20 # diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 7b7ddc50ac36..8933e1a62776 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -289,8 +289,9 @@ class NestedMatch: It matches a regex that it is followed by a delimiter, replacing occurrences only if all delimiters are paired. =20 - if r'\1' is used, it works just like re: it places there the - matched paired data with the delimiter stripped. + if r'\0' is used, it works on a similar way of using re.group(0): + it places the entire args of the matched paired data, with the + delimiter stripped. =20 If count is different than zero, it will replace at most count items. @@ -306,9 +307,9 @@ class NestedMatch: # Value, ignoring start/end delimiters value =3D line[end:pos - 1] =20 - # replaces \1 at the sub string, if \1 is used there + # replaces \0 at the sub string, if \0 is used there new_sub =3D sub - new_sub =3D new_sub.replace(r'\1', value) + new_sub =3D new_sub.replace(r'\0', value) =20 out +=3D new_sub =20 --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 374BE358D04; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=a9KNBOnKRSBRmMBlXBIEQU9Ij7w26wIflF8+BvFex0MkKGHoROA0OyMk6MMwMbtVkas5JWyRCISnph/l2mrGaeEVAPDkPZPG+8IMxpRMai89oB36lLzTeSUL18dFBK2+RIOiq2t1UJr32aS85t8Iqg7hVjM/sFboP+YlVOuU6go= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=4M1YK6ZJUo4rGAubeAeexggWDOfAzOxlq3GsBbCweOM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=efhSUbnfry5FLFXR2Ps+ylhIFaHQ9mEo2MLA6377tIa0yWpr81FNYxAafAaBV1sMaIZUAYsQtMS32WJg8IR2aoAJeDC4+Q7oNnzxrg+isPdx8agg2QGyVU+FLXR0CGRBx80P8KyVPfsE7VjsE9wcqpY9KPWBkYtYB/FkN72RH6Q= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=uGAySrqK; 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="uGAySrqK" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8DB7EC4AF09; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=4M1YK6ZJUo4rGAubeAeexggWDOfAzOxlq3GsBbCweOM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uGAySrqK+FUoVyvfESY+zPPzry/nIvZYIBTGlQVoAUsUni7DbNWAyr4MVctd06Saa 7mx6c57UyhnrBfZuCKDWBaX3Fxr/yVqUq5UgvCdBASa4py9n8B3XegPb9WPjWKSbDn ynMejjIx8CcRJE8ZMF5e6xcW/l3nZHATpMiiyV/BTYgtkPZ9W3D2NtL8eIfRESqHf3 j5wlPU3it89qGDFzG8yq0ASR1iXdPkJ6bB9HlCdJg+R17JglELBEfl/F0/Fx/xsr+e 4k3ou29LSiC3kwpZvA8sj4RLErf/1JarLl2nvF5s1D88tl+eqFW4RcgVp+uf5Dm9+f v857d/YNoMptg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVky-3UDo; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 19/41] docs: kdoc_re: make NestedMatch use KernRe Date: Sat, 31 Jan 2026 15:24: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 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 | 22 ++++++++--- 2 files changed, 32 insertions(+), 45 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 4d52a00acfad..3a5614106af7 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -153,32 +153,7 @@ struct_xforms =3D [ (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', r= e.S), r'dma_addr_t \1'), (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re= .S), r'__u32 \1'), (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1; u64= \1_array[VIRTIO_FEATURES_U64S]; }'), -] -# -# Struct regexes here are guaranteed to have the end delimiter matching -# the start delimiter. Yet, right now, only one replace group -# is allowed. -# -struct_nested_prefixes =3D [ - (re.compile(r'\bSTRUCT_GROUP\('), r'\0'), -] - -# -# Function Regexes here are guaranteed to have the end delimiter matching -# the start delimiter. -# -function_nested_prefixes =3D [ - (re.compile(r"__cond_acquires\s*\("), ""), - (re.compile(r"__cond_releases\s*\("), ""), - (re.compile(r"__acquires\s*\("), ""), - (re.compile(r"__releases\s*\("), ""), - (re.compile(r"__must_hold\s*\("), ""), - (re.compile(r"__must_not_hold\s*\("), ""), - (re.compile(r"__must_hold_shared\s*\("), ""), - (re.compile(r"__cond_acquires_shared\s*\("), ""), - (re.compile(r"__acquires_shared\s*\("), ""), - (re.compile(r"__releases_shared\s*\("), ""), - (re.compile(r"__attribute__\s*\("), ""), + (NestedMatch(r'\bSTRUCT_GROUP\('), r'\0'), ] =20 # @@ -210,6 +185,17 @@ function_xforms =3D [ (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2= "), (KernRe(r"__no_context_analysis\s*"), ""), (KernRe(r"__attribute_const__ +"), ""), + (NestedMatch(r"__cond_acquires\s*\("), ""), + (NestedMatch(r"__cond_releases\s*\("), ""), + (NestedMatch(r"__acquires\s*\("), ""), + (NestedMatch(r"__releases\s*\("), ""), + (NestedMatch(r"__must_hold\s*\("), ""), + (NestedMatch(r"__must_not_hold\s*\("), ""), + (NestedMatch(r"__must_hold_shared\s*\("), ""), + (NestedMatch(r"__cond_acquires_shared\s*\("), ""), + (NestedMatch(r"__acquires_shared\s*\("), ""), + (NestedMatch(r"__releases_shared\s*\("), ""), + (NestedMatch(r"__attribute__\s*\("), ""), ] =20 # @@ -230,7 +216,6 @@ var_xforms =3D [ # Ancillary functions # =20 - multi_space =3D KernRe(r'\s\s+') def trim_whitespace(s): """ @@ -424,8 +409,6 @@ class KernelDoc: # Place all potential outputs into an array self.entries =3D [] =20 - self.nested =3D NestedMatch() - # # We need Python 3.7 for its "dicts remember the insertion # order" guarantee @@ -523,14 +506,11 @@ class KernelDoc: # State flags self.state =3D state.NORMAL =20 - def apply_transforms(self, regex_xforms, nested_xforms, text): + def apply_transforms(self, xforms, text): """Apply a set of transforms to a block of text.""" - for search, subst in regex_xforms: + for search, subst in xforms: text =3D search.sub(subst, text) =20 - for search, sub in nested_xforms: - text =3D self.nested.sub(search, sub, text) - return text.strip() =20 def push_parameter(self, ln, decl_type, param, dtype, @@ -909,8 +889,7 @@ class KernelDoc: # Go through the list of members applying all of our transformatio= ns. # members =3D trim_private_members(members) - members =3D self.apply_transforms(struct_xforms, struct_nested_pre= fixes, - members) + members =3D self.apply_transforms(struct_xforms, members) =20 # # Deal with embedded struct and union members, and drop enums enti= rely. @@ -1125,9 +1104,7 @@ class KernelDoc: # # Apply the initial transformations. # - prototype =3D self.apply_transforms(function_xforms, - function_nested_prefixes, - prototype) + prototype =3D self.apply_transforms(function_xforms, prototype) =20 # Yes, this truly is vile. We are looking for: # 1. Return type (may be nothing if we're looking at a macro) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 8933e1a62776..e34d55c25680 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -200,7 +200,10 @@ class NestedMatch: # # FOO(arg1, arg2, arg3) =20 - def _search(self, regex, line): + def __init__(self, regex): + self.regex =3D KernRe(regex) + + def _search(self, line): """ Finds paired blocks for a regex that ends with a delimiter. =20 @@ -222,7 +225,7 @@ class NestedMatch: =20 stack =3D [] =20 - for match_re in regex.finditer(line): + for match_re in self.regex.finditer(line): start =3D match_re.start() offset =3D match_re.end() string_char =3D None @@ -270,7 +273,7 @@ class NestedMatch: yield start, offset, pos + 1 break =20 - def search(self, regex, line): + def search(self, line): """ This is similar to re.search: =20 @@ -278,11 +281,11 @@ class NestedMatch: returning occurrences only if all delimiters are paired. """ =20 - for t in self._search(regex, line): + for t in self._search(line): =20 yield line[t[0]:t[2]] =20 - def sub(self, regex, sub, line, count=3D0): + def sub(self, sub, line, count=3D0): """ This is similar to re.sub: =20 @@ -301,7 +304,7 @@ class NestedMatch: cur_pos =3D 0 n =3D 0 =20 - for start, end, pos in self._search(regex, line): + for start, end, pos in self._search(line): out +=3D line[cur_pos:start] =20 # Value, ignoring start/end delimiters @@ -328,3 +331,10 @@ class NestedMatch: out +=3D line[cur_pos:l] =20 return out + + def __repr__(self): + """ + Returns a displayable version of the class init. + """ + + return f'NestedMatch("{self.regex.regex.pattern}")' --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 3BC61358D1A; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=g7SmVFHz/nUiOdzuliDM8d6OFBvuw34KC+4OlG43OmTjG3tRmg08kS4QWDDpuEfv1X7K1mWrqRVHXIHA6+hy5+got6vf2es2Em22s4pa7cTpHYfi100TYuleWu8DrFQp8tEvVABZcXrzZN3EpLcmeWeMVFC6z2I5KNtSzhXkBKY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=exVw90yVLaIyCuiKNYXLsf4VR9OXQdWgf2cZhrnzV2Q=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Ar+jO2XD+JGxXUyZ/07D7YDEjlzF23EDwZnodyms0bi7pUK7m3kK/ouDZrdswXrBUN6GMegYmyEEEsw2uHeCNEY88mshTJNLYz5nCPrW/GXU5rWerZIyZtw6rBbqVNBI3IZSsaRZQ6uk0yfUiNqm8D+mnYmnTKH5vS4mrt6cJhA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Jhqi27Bi; 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="Jhqi27Bi" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9414FC2BCF6; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=exVw90yVLaIyCuiKNYXLsf4VR9OXQdWgf2cZhrnzV2Q=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Jhqi27BiIT4Cy//A3hEMRtGYKj50D5duVDfRfGkKdNgh6LD77COjmfBm64oC/rxgq Chi6eJlVjvFKzFZuicwjfCRd11XLJCUS4y/RL0kbRwZ93UpgHzfdcmU7UGDcOZrvVc b0AQNa8jXCKYwbGEB4m4iBCrAiRwlde4FiB95ffOYcdlvFbEW50gZvUNn9bI+RzTgA YvT9Fp7wKQG7suV9128aCSi0eZxhIBzXVaHZA1C7ebawmkE7z0rtN5py4KusvhVf45 Mf4siTxDUozZqHAqMAb3GDntztQCBlHnv0NkDutJpfgao47cERvK1EirAQQ6kCAmTq M7HeP0nAPIEaA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVl2-3bSB; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 20/41] docs: kdoc_re: add support on NestedMatch for argument replacement Date: Sat, 31 Jan 2026 15:24:54 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Currently, NestedMatch has very limited support for aguments replacement: it is all or nothing. Add support to allow replacing individual arguments as well. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 84 ++++++++++++++++++++++---------- 1 file changed, 59 insertions(+), 25 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index e34d55c25680..858cc688a58f 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -177,29 +177,6 @@ class NestedMatch: will ignore the search string. """ =20 - # TODO: make NestedMatch handle multiple match groups - # - # Right now, regular expressions to match it are defined only up to - # the start delimiter, e.g.: - # - # \bSTRUCT_GROUP\( - # - # is similar to: STRUCT_GROUP\((.*)\) - # except that the content inside the match group is delimiter-aligned. - # - # The content inside parentheses is converted into a single replace - # group (e.g. r`\1'). - # - # It would be nice to change such definition to support multiple - # match groups, allowing a regex equivalent to: - # - # FOO\((.*), (.*), (.*)\) - # - # it is probably easier to define it not as a regular expression, but - # with some lexical definition like: - # - # FOO(arg1, arg2, arg3) - def __init__(self, regex): self.regex =3D KernRe(regex) =20 @@ -285,6 +262,59 @@ class NestedMatch: =20 yield line[t[0]:t[2]] =20 + @staticmethod + def _split_args(all_args, delim=3D","): + """ + Helper method to split comma-separated function arguments + or struct elements, if delim is set to ";". + + It returns a list of arguments that can be used later on by + the sub() method. + """ + args =3D [all_args] + stack =3D [] + arg_start =3D 0 + string_char =3D None + escape =3D False + + for idx, d in enumerate(all_args): + if escape: + escape =3D False + continue + + if string_char: + if d =3D=3D '\\': + escape =3D True + elif d =3D=3D string_char: + string_char =3D None + + continue + + if d in ('"', "'"): + string_char =3D d + continue + + if d in DELIMITER_PAIRS: + end =3D DELIMITER_PAIRS[d] + + stack.append(end) + continue + + if stack and d =3D=3D stack[-1]: + stack.pop() + continue + + if d =3D=3D delim and not stack: + args.append(all_args[arg_start:idx].strip()) + arg_start =3D idx + 1 + + # Add the last argument (if any) + last =3D all_args[arg_start:].strip() + if last: + args.append(last) + + return args + def sub(self, sub, line, count=3D0): """ This is similar to re.sub: @@ -310,9 +340,13 @@ class NestedMatch: # Value, ignoring start/end delimiters value =3D line[end:pos - 1] =20 - # replaces \0 at the sub string, if \0 is used there + # replace arguments new_sub =3D sub - new_sub =3D new_sub.replace(r'\0', value) + if "\\" in sub: + args =3D self._split_args(value) + + new_sub =3D re.sub(r'\\(\d+)', + lambda m: args[int(m.group(1))], new_sub) =20 out +=3D new_sub =20 --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 436A53590A4; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=hdDRfeaZPq0X8lFmcM4pMNxB0KJsGx7OClfkl0TGkjPtvj2a+DUtxfClpo901/X6Jne0mKNV9tlRC9k9pVoDOHQdAkF0d0tRU410FLCu2ANHo6Hu/PHoYQX6QuK3HTVKaoJqOReoMbzVaqaTBlq4q0WY0V6bOy+auN4QxpQ07Cs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=yHTvoLbqPGgQzPgBOzeytRzZYEiySFBnO0ERiQ2SquU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=nvvtcUAYp9W5LTC9FmeBrQwMTmpN09ZWxRejUwWShncSQYqfPXsPAqhKbQtcxpKlNCepumCHfLQKVjLF1BTVfvb7K72YHPAfIK+/dAK1nMGoyX0Ey14G6pbvHndxdOWwMu7wiK5IRVWYaMBiZI7BASHH7RpdDwYx/u0mfN5V0to= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ih6ncNpr; 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="ih6ncNpr" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A8E79C2BCFF; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=yHTvoLbqPGgQzPgBOzeytRzZYEiySFBnO0ERiQ2SquU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ih6ncNprGLq//Yqu8qYVTYKtlrKIjoBVXKfVLoguaydHod2z+8k7gZ6WyA/N99XnD aVmqJ1ksWogW5q1zJ91xrSLLDm8+9PFa7aAf5ibzhqslu1QAOCI58+mOTpypB3Tfhh 24l13tvvffnuD1TAOLXKEkN36JwdtG8XHPr/hbglzW0F4e1U8+yY0udtZ0IC+VO2/e Mv1cgFZh8gH6ux25BlTIZJjc4wgHzRTvTe1G1uflypKUwYQj4RLxZvVulqDimJURbK DhHUMw4HXQzQn3tlxcnDOdXyskwU27kvekbm8SddgOvCAzKSCTc0c3aszXzWrnv3P+ WjC4vo4U+ZG3g== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVl6-3ii2; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 21/41] docs: kdoc_parser: better handle struct_group macros Date: Sat, 31 Jan 2026 15:24:55 +0100 Message-ID: <5429d80aaf51f22a8b840f269ef2e0a2b55bca82.1769867953.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 3a5614106af7..d2eb93f9d489 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -124,10 +124,11 @@ struct_xforms =3D [ # matched. So, the implementation to drop STRUCT_GROUP() will be # handled in separate. # - (KernRe(r'\bstruct_group\s*\(([^,]*,)', re.S), r'STRUCT_GROUP('), - (KernRe(r'\bstruct_group_attr\s*\(([^,]*,){2}', re.S), r'STRUCT_GROUP(= '), - (KernRe(r'\bstruct_group_tagged\s*\(([^,]*),([^,]*),', re.S), r'struct= \1 \2; STRUCT_GROUP('), - (KernRe(r'\b__struct_group\s*\(([^,]*,){3}', re.S), r'STRUCT_GROUP('), + (NestedMatch(r'\bstruct_group\s*\('), r'\2'), + (NestedMatch(r'\bstruct_group_attr\s*\('), r'\3'), + (NestedMatch(r'\bstruct_group_tagged\s*\('), r'struct \1 { \3 } \2;'), + (NestedMatch(r'\b__struct_group\s*\('), r'\4'), + # # Replace macros # @@ -153,7 +154,6 @@ struct_xforms =3D [ (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', r= e.S), r'dma_addr_t \1'), (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re= .S), r'__u32 \1'), (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1; u64= \1_array[VIRTIO_FEATURES_U64S]; }'), - (NestedMatch(r'\bSTRUCT_GROUP\('), r'\0'), ] =20 # --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 41AF7358D38; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=CYA7PlC1xDqbBdyqYBQzOWqQL0/rMlp3P4IzoD1x+Ct5wRMkDHPnapns7myUAIp4ICQK9z6xmMV5y6prukj0JXAcjlav/EcHkU07obvRNUKJ/NgFU4/J6rs5qBA0dRaOrW2QSQuZ4EIvZsZ3a8sJfbuMTpBanio21TMw04sH4Uo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=k3Exn/v9pCnRWah8GG4TA6vNRtpJjwGM1Bhrsrl1p0Y=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=IoNhszoIKRGnbsIejCxXJGGKaGslhkLkP7w2JWAeKfY6QbBeNhr4X9gX++JYM1WYxtrpGDu0CvoWQqN//ukqXgcCNKiHZBZvLfwHQ6alI4EEiuARlCLvEd+febHBKw1IkmKN8gDcjiS0IieZwL8Gy86Rke8KQnPuP3NwHlA9NCM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=OvUudNjX; 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="OvUudNjX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9C03EC2BCF7; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=k3Exn/v9pCnRWah8GG4TA6vNRtpJjwGM1Bhrsrl1p0Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=OvUudNjX9xrBKQrvkqkcZvMH601ogLtpT+0oXRR2dpWAB8f/780ewGG6WMxsM4r+R /qWk8x9l0KQ+MgNRhpX4po7LY32bs0eG0GFxYyyirb35OPfCFmfoIPV8AjDA7/iJI2 eKvAxJ1V1tSeElsStiIz0ihE97MXE0GWf7j0B0YuflF9atJAjEJOkQ6qM5gxq/rScA G8jmIUndsVxh2xGzjPbaEOtmhKFvz6p0RF0FzQu9w5htZQCpQxd+ViYBW0q8tmTZh6 DqT4cEGbpvCSHbwhiJbhyPU5D70/byqprc2r1nJzAmrVm0FZsXWVDxFGpsfuS2US+T ya7v53B2g7Zhg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVlA-3q05; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 22/41] docs: kdoc_re: fix a parse bug on struct page_pool_params Date: Sat, 31 Jan 2026 15:24:56 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab 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 858cc688a58f..5f455ffff7b2 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -201,6 +201,9 @@ class NestedMatch: """ =20 stack =3D [] + start =3D 0 + offset =3D 0 + pos =3D 0 =20 for match_re in self.regex.finditer(line): start =3D match_re.start() @@ -250,6 +253,11 @@ class NestedMatch: yield start, offset, pos + 1 break =20 + # When /* private */ is used, it may end the end delimiterq + if stack: + stack.pop() + yield start, offset, len(line) + 1 + def search(self, line): """ This is similar to re.search: --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 42387358D3A; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=FNob03bQjTuIY7U/jySsgwHzluvfUh01uW9lYqjxemQlDpyyHw9XBlHneUjlTk4pAzqxrMkLK5ksYqEN0AnocYR5y8FPO5y1az1PmisS/rbWYgcxYFduWoPj2NxO/+YaYQMWXOoGuM9wjNs3ez78I2cx/+6VvMEzXujh1MMU99g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=3ksnXE7vkIV4Gy30ihYdParnXgZsaJn15iVxtzuvJ4c=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=CNJRLt5hfswOfCA+A/sKeuQL2b1CdxJSHhlf/RgPeKE7VFwExFqL6DZnm/aBN+kpjOdj15jJkxJWEBhk+ddUUFsHu0R1A5Ts6B6jMqN815J2cjyDwuomXTU9tMnoryL7SRfcCh2BxD4SPRlA+cJhk5EuxFeSucbxrZEiO1zkWyM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=maeQ6NIQ; 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="maeQ6NIQ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A7430C2BD00; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=3ksnXE7vkIV4Gy30ihYdParnXgZsaJn15iVxtzuvJ4c=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=maeQ6NIQqyOmmMZ1bq5xg5TRiG9YE2TRuw+KFDcCAsstytrpri5AUbDdMoLYCiXr/ Rzio2GydR6Dv/NeY8AaELoinK8d3kO8b14GsDxBQOXiKDSIfrvkW8VRmUcxB9cEZgC fXjwoxKc20EccgAV+k3X/REHlwxfOR/k6YuxvsezhNWh+8S+X8rPO6+cVeCa2XjZOM GnM0CzQiWWMBEOlM30V2pP+ybuhnqmpUJToGMueBZ32g3EaVRy1gC7nL+NVQabpkRV UqhQyt5cLn+oBww9CIfdBLoka3VzVOScA55A2YjFcQ6k823LBoIjCs56dpbGTYn3wR 8nre1pj0Z7i+g== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVlE-3xBx; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 23/41] docs: kdoc_re: add a helper class to declare C function matches Date: Sat, 31 Jan 2026 15:24:57 +0100 Message-ID: <019e85b047f25aa5472d447e1ed087cd077a79f6.1769867953.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Add a more convenient class to match C functions and avoiding issues at the beginning and ending of NestedMatch inits. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 5f455ffff7b2..a49b42e3d189 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -380,3 +380,14 @@ class NestedMatch: """ =20 return f'NestedMatch("{self.regex.regex.pattern}")' + + +class CFunction(NestedMatch): + r""" + Variant of NestedMatch. + + It overrides the init method to ensure that the regular expression will + start with a ``\b`` and end with a C function delimiter (open parenthe= sis). + """ + def __init__(self, regex): + self.regex =3D KernRe(r"\b" + regex + r"\s*\(") --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 427FC358D3D; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=CPU684mxzwFo1MMXDuKsa9WT8zNdL8I9p+8vLZnSwyXdy2bYR8a9vVTjmBSdS3yUXEOm1xhHE/Es72Up+kfx+L4lXEqxPXip51ry5SAMZt+FtagMe4Cjish1uPcSGuAK1mVQf8A7CD9cbnuWg6UQoczQaHjJMkgVJMV2SHBfbVI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=C6CeWuwXNWfLjH/HHfru4lb9lJd9uRNWvYwHu3+yiQs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=EpBY8PWZNJnpVdJm0PAljIJrcvHgzbH/nyebryZiODhkQtU2/tBoYTLULUH2ylUHms51qgSK85WMzh6V59tYcUCfxjIHZMfeEgyHKUd6j5TII+VLXgsctQe13wqErgr0uis/qfHJSq2p+4WOvFgUDTH/dRyESC84PcnqoD+QLJw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RkeM9Nri; 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="RkeM9Nri" Received: by smtp.kernel.org (Postfix) with ESMTPSA id ADCACC32786; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=C6CeWuwXNWfLjH/HHfru4lb9lJd9uRNWvYwHu3+yiQs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RkeM9Nrie3xNQ4HWedROr+6WaD2mh/DbAVra2t2JekLYUhCRXUO5h1jWn7zq01ekl ty+h8IZvW0lKLA+utKar+4BKpIxmJnvYAeHINMYJe0ABNrVdCQumBGKkHc1LzPN+1w 17hsffFDWUIHZpZm35tVcgpviJ2Z9tdJZJDk/iPF6eWdCdkwo9jJVuzQhzyzlP92o8 8A8zBatsh0c2161cT72F6aPDEQ2iZDvnWwY5Yfxr92x+2R0zgfezCncIJTUWhS6iXi bv14s5/6dXYb5yhTRJV1ghw787Sy+e1XedJRNUvO2HEEZgUZdNHFXtz/awTcArRy4t lqeL2ZMlMqANw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVlI-44GF; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 24/41] docs: kdoc_parser: use the new CFunction class Date: Sat, 31 Jan 2026 15:24:58 +0100 Message-ID: <06eaea98108e280144f088cbb3f35bf1d2fb5937.1769867953.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The match logic for transforms becomes a lot clearer if we use CFunction convenient alias class instead of NestedMatch. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 38 ++++++++++++++-------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index d2eb93f9d489..50d57c6799bb 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -13,7 +13,7 @@ import sys import re from pprint import pformat =20 -from kdoc.kdoc_re import NestedMatch, KernRe +from kdoc.kdoc_re import CFunction, KernRe from kdoc.kdoc_item import KdocItem =20 # @@ -119,22 +119,22 @@ struct_xforms =3D [ # # As it doesn't properly match the end parenthesis on some cases. # - # So, a better solution was crafted: there's now a NestedMatch + # So, a better solution was crafted: there's now a CFunction # class that ensures that delimiters after a search are properly # matched. So, the implementation to drop STRUCT_GROUP() will be # handled in separate. # - (NestedMatch(r'\bstruct_group\s*\('), r'\2'), - (NestedMatch(r'\bstruct_group_attr\s*\('), r'\3'), - (NestedMatch(r'\bstruct_group_tagged\s*\('), r'struct \1 { \3 } \2;'), - (NestedMatch(r'\b__struct_group\s*\('), r'\4'), + (CFunction('struct_group'), r'\2'), + (CFunction('struct_group_attr'), r'\3'), + (CFunction('struct_group_tagged'), r'struct \1 { \3 } \2;'), + (CFunction('__struct_group'), r'\4'), =20 # # Replace macros # - # TODO: use NestedMatch for FOO($1, $2, ...) matches + # TODO: use CFunction on all FOO($1, $2, ...) matches # - # it is better to also move those to the NestedMatch logic, + # it is better to also move those to the CFunction logic, # to ensure that parentheses will be properly matched. # (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re.S), @@ -185,17 +185,17 @@ function_xforms =3D [ (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2= "), (KernRe(r"__no_context_analysis\s*"), ""), (KernRe(r"__attribute_const__ +"), ""), - (NestedMatch(r"__cond_acquires\s*\("), ""), - (NestedMatch(r"__cond_releases\s*\("), ""), - (NestedMatch(r"__acquires\s*\("), ""), - (NestedMatch(r"__releases\s*\("), ""), - (NestedMatch(r"__must_hold\s*\("), ""), - (NestedMatch(r"__must_not_hold\s*\("), ""), - (NestedMatch(r"__must_hold_shared\s*\("), ""), - (NestedMatch(r"__cond_acquires_shared\s*\("), ""), - (NestedMatch(r"__acquires_shared\s*\("), ""), - (NestedMatch(r"__releases_shared\s*\("), ""), - (NestedMatch(r"__attribute__\s*\("), ""), + (CFunction("__cond_acquires"), ""), + (CFunction("__cond_releases"), ""), + (CFunction("__acquires"), ""), + (CFunction("__releases"), ""), + (CFunction("__must_hold"), ""), + (CFunction("__must_not_hold"), ""), + (CFunction("__must_hold_shared"), ""), + (CFunction("__cond_acquires_shared"), ""), + (CFunction("__acquires_shared"), ""), + (CFunction("__releases_shared"), ""), + (CFunction("__attribute__"), ""), ] =20 # --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 491923590BE; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=gRCWJxPB5aEQdK9vvueM/KID83Ertx1TfN2VcReUHtsVPU67lMTeM1DvNZ+HOVOOq+HmQzsLFlu12zisoXl2voNT8QUGMRUsFosVKAMTfIsjC2hOHcWjdRMo3eZHfq4pprvYxzY6Mpw+vf/gLG6ksoxOAsKVPveraDExVfpgldY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=PjcYZUAUNaiqUM2WGTjsaVLZOk4Wa72JQZXaktFxmLA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=jDsfYW/8dk2EGf/XKc3DKd/vRAqQk1qO3GuJfUuWx0oR89M3WahJtOEZBvoboDFvSdxfRlgm+ubA7fQVwgkcwFylN97XCe+4R/MLJ3Uaxx5D4Da2AkXgl55bho8zXsUrha61WfOwL0Dzj/2Zdd4J8zgKkxwxldhTZg3OB0wUfGk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=itO0YwQZ; 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="itO0YwQZ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B60E0C2BCB4; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=PjcYZUAUNaiqUM2WGTjsaVLZOk4Wa72JQZXaktFxmLA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=itO0YwQZpIhW76BAuJiH93sAQFczal11Ra0KiNpY9EcXSC3ymmLIypzntUYYzoQ0g yyIlO/SwbI5WDTenKTX0cHWL6npF88k3qPYSMwknuD8JNELfOjKIawqmjoJ2BFA/vc 1EC78b+yPTddRm9OIN5kE3Gm8I9r8lQA6YWPJRoj4A785sR1Y7DoBoHpGy1totldS6 33lBlJ2SBS9Bv/JGW6hmUUzhGxXEIy1ArhLnmC97F5CDW2DrOZAoIo0JxFhU1gZxeR 6vCRZJPkqYjep91x15m0vecyfcIfujpsw9QBtJ8U64SlxkdN04RuL0V8oNB+qCa73P 8VIzzXg6gQ8LQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBuZ-0000000AVlN-4Buk; Sat, 31 Jan 2026 15:25:20 +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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 25/41] docs: kdoc_parser: minimize differences with struct_group_tagged Date: Sat, 31 Jan 2026 15:24:59 +0100 Message-ID: <3e6a3336d4f62f65df3ce1b464c8233fc59611b0.1769867953.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab While the previous version does a better job representing the actual struct, it ends losing documentation from each member. Change the replacements to minimize such changes. With that, the only differences before/after using NestedMatch new replacement logic are (at man page output): --- before.log 2026-01-29 06:14:20.163592584 +0100 +++ after.log 2026-01-29 06:32:04.811370234 +0100 @@ -1573701 +1573701 @@ -.BI " struct ice_health_tx_hang_buf tx_hang_buf;" +.BI " struct ice_health_tx_hang_buf tx_hang_buf;" @@ -4156451 +4156451 @@ -.BI " struct libeth_fq_fp fp;" +.BI " struct libeth_fq_fp fp;" @@ -4164041 +4164041 @@ -.BI " struct libeth_xskfq_fp fp;" +.BI " struct libeth_xskfq_fp fp;" @@ -4269434 +4269434 @@ -.BI " struct page_pool_params_fast fast;" +.BI " struct page_pool_params_fast fast;" @@ -4269452 +4269452 @@ -.BI " struct page_pool_params_slow slow;" +.BI " struct page_pool_params_slow slow;" @@ -4269454 +4269454 @@ -.BI " STRUCT_GROUP( struct net_device *netdev;" +.BI " struct net_device *netdev;" e.g. basically whitespaces, plus a fix NestedMatch to better handle /* private */ comments. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 50d57c6799bb..1e8e156e2a9e 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -126,7 +126,7 @@ struct_xforms =3D [ # (CFunction('struct_group'), r'\2'), (CFunction('struct_group_attr'), r'\3'), - (CFunction('struct_group_tagged'), r'struct \1 { \3 } \2;'), + (CFunction('struct_group_tagged'), r'struct \1 \2; \3'), (CFunction('__struct_group'), r'\4'), =20 # --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 9C6ED35B621; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=soTbzcFIx62ZMwb8l3XVMll3YmtF0fzutk6IOLdncSBkN+fTn19p45TB3JT7Vu7gh8Ck6BQsBjd4RS/qJStHC+TVf9SsDxahJ0v23nFWGGyhchwjIkwipZUg8dFTuOdlI+GXB7RZuIvqPe4iVuM8uZLp4/IIl78G0/BWcHpSLpQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=FQwon0lGCEEl3a0ZrhHyVTozHezlG7Q5rbiRVSPsdCM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=L06FUzwDcJV3TgmoBjK1nAKtCSQDD3XLfptkkO57n+t1AnwaUHY6J5O4+lI9POeb5TsFP40kCgiELr0p8ZL3c68Xtk9VhcWyFNt3+dRck/c2P2wuSDcwAceCEzsjoV9V2BgAUozahJ6NuTwvPD0tQ2CdssS84OL/IF26lsa1qDE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=qf3OnObv; 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="qf3OnObv" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C555FC2BCC4; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869522; bh=FQwon0lGCEEl3a0ZrhHyVTozHezlG7Q5rbiRVSPsdCM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=qf3OnObvsEFFPnhT3+O8KOqp/K+XwsoKEtc+YF8lt9UkxJbB7PxET8ThukOfyEvSn 6jnEo6D3ildurzqP6tQ2kB8Ql1hpleDK99D47s3d3C48XUE9uRnoBCx3CyRzFX5anu 36GgeiDO3s2+t7FuVw5eMiSa8tEvAGikz4l3EWF46NmIC38pVSYJiHLqFZJf098R0J CKwGMiUPe8SuV5l5RxaSYY4xggo178IO4MllCs5UXux/4dRkqyt38paYfvxxc4UeG/ XjIsIVdEksIoo9HyOj5lSUxdv7QnpBbSkVyMSv8L4D+Y+u2jsVEN/n4+awZDOdtUxw FwpLYxzQTErWA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVlT-07B5; Sat, 31 Jan 2026 15:25: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, "Gustavo A. R. Silva" , Aleksandr Loktionov , Kees Cook , Mauro Carvalho Chehab , Randy Dunlap , Shuah Khan Subject: [PATCH v4 26/41] docs: kdoc_parser: move transform lists to a separate file Date: Sat, 31 Jan 2026 15:25:00 +0100 Message-ID: <543bc5c380a64a85d1bd656e0e7045626398206c.1769867953.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Over the time, most of the changes at kernel-doc are related to maintaining a list of transforms to convert macros into pure C code. Place such transforms on a separate module, to cleanup the parser module. While here, drop the now obsolete comment about the two-steps logic to handle struct_group macros. There is an advantage on that: QEMU also uses our own kernel-doc, but the xforms list there is different. By placing it on a separate module, we can minimize the differences and make it easier to keep QEMU in sync with Kernel upstream. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- Documentation/tools/kdoc_parser.rst | 8 ++ tools/lib/python/kdoc/kdoc_files.py | 3 +- tools/lib/python/kdoc/kdoc_parser.py | 147 ++------------------------ tools/lib/python/kdoc/xforms_lists.py | 117 ++++++++++++++++++++ 4 files changed, 133 insertions(+), 142 deletions(-) create mode 100644 tools/lib/python/kdoc/xforms_lists.py diff --git a/Documentation/tools/kdoc_parser.rst b/Documentation/tools/kdoc= _parser.rst index 03ee54a1b1cc..55b202173195 100644 --- a/Documentation/tools/kdoc_parser.rst +++ b/Documentation/tools/kdoc_parser.rst @@ -4,6 +4,14 @@ Kernel-doc parser stage =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 +C replacement rules used by the parser +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. automodule:: lib.python.kdoc.xforms_lists + :members: + :show-inheritance: + :undoc-members: + File handler classes =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kd= oc_files.py index 022487ea2cc6..7357c97a4b01 100644 --- a/tools/lib/python/kdoc/kdoc_files.py +++ b/tools/lib/python/kdoc/kdoc_files.py @@ -15,6 +15,7 @@ import os import re =20 from kdoc.kdoc_parser import KernelDoc +from kdoc.xforms_lists import CTransforms from kdoc.kdoc_output import OutputFormat =20 =20 @@ -117,7 +118,7 @@ class KernelFiles(): if fname in self.files: return =20 - doc =3D KernelDoc(self.config, fname) + doc =3D KernelDoc(self.config, fname, CTransforms) export_table, entries =3D doc.parse_kdoc() =20 self.export_table[fname] =3D export_table diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 1e8e156e2a9e..a280fe581937 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -75,142 +75,6 @@ doc_begin_func =3D KernRe(str(doc_com) + # initial " = * ' # struct_args_pattern =3D r'([^,)]+)' =20 -struct_xforms =3D [ - # Strip attributes - (KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", flags=3Dre.I |= re.S, cache=3DFalse), ' '), - (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), - (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), - (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), - (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ' '), - (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ' '), - (KernRe(r'\s*__packed\s*', re.S), ' '), - (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), - (KernRe(r'\s*__private', re.S), ' '), - (KernRe(r'\s*__rcu', re.S), ' '), - (KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '), - (KernRe(r'\s*____cacheline_aligned', re.S), ' '), - (KernRe(r'\s*__cacheline_group_(begin|end)\([^\)]+\);'), ''), - # - # Unwrap struct_group macros based on this definition: - # __struct_group(TAG, NAME, ATTRS, MEMBERS...) - # which has variants like: struct_group(NAME, MEMBERS...) - # Only MEMBERS arguments require documentation. - # - # Parsing them happens on two steps: - # - # 1. drop struct group arguments that aren't at MEMBERS, - # storing them as STRUCT_GROUP(MEMBERS) - # - # 2. remove STRUCT_GROUP() ancillary macro. - # - # The original logic used to remove STRUCT_GROUP() using an - # advanced regex: - # - # \bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*; - # - # with two patterns that are incompatible with - # Python re module, as it has: - # - # - a recursive pattern: (?1) - # - an atomic grouping: (?>...) - # - # I tried a simpler version: but it didn't work either: - # \bSTRUCT_GROUP\(([^\)]+)\)[^;]*; - # - # As it doesn't properly match the end parenthesis on some cases. - # - # So, a better solution was crafted: there's now a CFunction - # class that ensures that delimiters after a search are properly - # matched. So, the implementation to drop STRUCT_GROUP() will be - # handled in separate. - # - (CFunction('struct_group'), r'\2'), - (CFunction('struct_group_attr'), r'\3'), - (CFunction('struct_group_tagged'), r'struct \1 \2; \3'), - (CFunction('__struct_group'), r'\4'), - - # - # Replace macros - # - # TODO: use CFunction on all FOO($1, $2, ...) matches - # - # it is better to also move those to the CFunction logic, - # to ensure that parentheses will be properly matched. - # - (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re.S), - r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), - (KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)', re.S), - r'DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'), - (KernRe(r'DECLARE_BITMAP\s*\(' + struct_args_pattern + r',\s*' + struc= t_args_pattern + r'\)', - re.S), r'unsigned long \1[BITS_TO_LONGS(\2)]'), - (KernRe(r'DECLARE_HASHTABLE\s*\(' + struct_args_pattern + r',\s*' + st= ruct_args_pattern + r'\)', - re.S), r'unsigned long \1[1 << ((\2) - 1)]'), - (KernRe(r'DECLARE_KFIFO\s*\(' + struct_args_pattern + r',\s*' + struct= _args_pattern + - r',\s*' + struct_args_pattern + r'\)', re.S), r'\2 *\1'), - (KernRe(r'DECLARE_KFIFO_PTR\s*\(' + struct_args_pattern + r',\s*' + - struct_args_pattern + r'\)', re.S), r'\2 *\1'), - (KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\s*\(' + struct_args_pattern + r',\= s*' + - struct_args_pattern + r'\)', re.S), r'\1 \2[]'), - (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', r= e.S), r'dma_addr_t \1'), - (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re= .S), r'__u32 \1'), - (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1; u64= \1_array[VIRTIO_FEATURES_U64S]; }'), -] - -# -# Transforms for function prototypes -# -function_xforms =3D [ - (KernRe(r"^static +"), ""), - (KernRe(r"^extern +"), ""), - (KernRe(r"^asmlinkage +"), ""), - (KernRe(r"^inline +"), ""), - (KernRe(r"^__inline__ +"), ""), - (KernRe(r"^__inline +"), ""), - (KernRe(r"^__always_inline +"), ""), - (KernRe(r"^noinline +"), ""), - (KernRe(r"^__FORTIFY_INLINE +"), ""), - (KernRe(r"__init +"), ""), - (KernRe(r"__init_or_module +"), ""), - (KernRe(r"__deprecated +"), ""), - (KernRe(r"__flatten +"), ""), - (KernRe(r"__meminit +"), ""), - (KernRe(r"__must_check +"), ""), - (KernRe(r"__weak +"), ""), - (KernRe(r"__sched +"), ""), - (KernRe(r"_noprof"), ""), - (KernRe(r"__always_unused *"), ""), - (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""), - (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""), - (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), - (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2= "), - (KernRe(r"__no_context_analysis\s*"), ""), - (KernRe(r"__attribute_const__ +"), ""), - (CFunction("__cond_acquires"), ""), - (CFunction("__cond_releases"), ""), - (CFunction("__acquires"), ""), - (CFunction("__releases"), ""), - (CFunction("__must_hold"), ""), - (CFunction("__must_not_hold"), ""), - (CFunction("__must_hold_shared"), ""), - (CFunction("__cond_acquires_shared"), ""), - (CFunction("__acquires_shared"), ""), - (CFunction("__releases_shared"), ""), - (CFunction("__attribute__"), ""), -] - -# -# Transforms for variable prototypes -# -var_xforms =3D [ - (KernRe(r"__read_mostly"), ""), - (KernRe(r"__ro_after_init"), ""), - (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ""), - (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ""), - (KernRe(r"LIST_HEAD\(([\w_]+)\)"), r"struct list_head \1"), - (KernRe(r"(?://.*)$"), ""), - (KernRe(r"(?:/\*.*\*/)"), ""), - (KernRe(r";$"), ""), -] =20 # # Ancillary functions @@ -394,11 +258,12 @@ class KernelDoc: #: String to write when a parameter is not described. undescribed =3D "-- undescribed --" =20 - def __init__(self, config, fname): + def __init__(self, config, fname, xforms): """Initialize internal variables""" =20 self.fname =3D fname self.config =3D config + self.xforms =3D xforms =20 # Initial state for the state machines self.state =3D state.NORMAL @@ -889,7 +754,7 @@ class KernelDoc: # Go through the list of members applying all of our transformatio= ns. # members =3D trim_private_members(members) - members =3D self.apply_transforms(struct_xforms, members) + members =3D self.apply_transforms(self.xforms.struct_xforms, membe= rs) =20 # # Deal with embedded struct and union members, and drop enums enti= rely. @@ -1011,8 +876,7 @@ class KernelDoc: # Drop comments and macros to have a pure C prototype # if not declaration_name: - for r, sub in var_xforms: - proto =3D r.sub(sub, proto) + proto =3D self.apply_transforms(self.xforms.var_xforms, proto) =20 proto =3D proto.rstrip() =20 @@ -1104,7 +968,8 @@ class KernelDoc: # # Apply the initial transformations. # - prototype =3D self.apply_transforms(function_xforms, prototype) + prototype =3D self.apply_transforms(self.xforms.function_xform= s, + prototype) =20 # Yes, this truly is vile. We are looking for: # 1. Return type (may be nothing if we're looking at a macro) diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/= xforms_lists.py new file mode 100644 index 000000000000..88968bafdb78 --- /dev/null +++ b/tools/lib/python/kdoc/xforms_lists.py @@ -0,0 +1,117 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright(c) 2026: Mauro Carvalho Chehab . + +import re + +from kdoc.kdoc_re import CFunction, KernRe + +struct_args_pattern =3D r'([^,)]+)' + +class CTransforms: + """ + Data class containing a long set of transformations to turn + structure member prefixes, and macro invocations and variables + into something we can parse and generate kdoc for. + """ + + #: Transforms for structs and unions + struct_xforms =3D [ + # Strip attributes + (KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", flags=3Dre= .I | re.S, cache=3DFalse), ' '), + (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ' '), + (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ' '), + (KernRe(r'\s*__packed\s*', re.S), ' '), + (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), + (KernRe(r'\s*__private', re.S), ' '), + (KernRe(r'\s*__rcu', re.S), ' '), + (KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '), + (KernRe(r'\s*____cacheline_aligned', re.S), ' '), + (KernRe(r'\s*__cacheline_group_(begin|end)\([^\)]+\);'), ''), + + (CFunction('struct_group'), r'\2'), + (CFunction('struct_group_attr'), r'\3'), + (CFunction('struct_group_tagged'), r'struct \1 \2; \3'), + (CFunction('__struct_group'), r'\4'), + + # + # Replace macros + # + # TODO: use CFunction on all FOO($1, $2, ...) matches + # + # it is better to also move those to the CFunction logic, + # to ensure that parentheses will be properly matched. + # + (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re.S), + r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), + (KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)', re.S), + r'DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'), + (KernRe(r'DECLARE_BITMAP\s*\(' + struct_args_pattern + r',\s*' + s= truct_args_pattern + r'\)', + re.S), r'unsigned long \1[BITS_TO_LONGS(\2)]'), + (KernRe(r'DECLARE_HASHTABLE\s*\(' + struct_args_pattern + r',\s*' = + struct_args_pattern + r'\)', + re.S), r'unsigned long \1[1 << ((\2) - 1)]'), + (KernRe(r'DECLARE_KFIFO\s*\(' + struct_args_pattern + r',\s*' + st= ruct_args_pattern + + r',\s*' + struct_args_pattern + r'\)', re.S), r'\2 *\1'), + (KernRe(r'DECLARE_KFIFO_PTR\s*\(' + struct_args_pattern + r',\s*' + + struct_args_pattern + r'\)', re.S), r'\2 *\1'), + (KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\s*\(' + struct_args_pattern + = r',\s*' + + struct_args_pattern + r'\)', re.S), r'\1 \2[]'), + (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)= ', re.S), r'dma_addr_t \1'), + (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)'= , re.S), r'__u32 \1'), + (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1;= u64 \1_array[VIRTIO_FEATURES_U64S]; }'), + ] + + #: Transforms for function prototypes + function_xforms =3D [ + (KernRe(r"^static +"), ""), + (KernRe(r"^extern +"), ""), + (KernRe(r"^asmlinkage +"), ""), + (KernRe(r"^inline +"), ""), + (KernRe(r"^__inline__ +"), ""), + (KernRe(r"^__inline +"), ""), + (KernRe(r"^__always_inline +"), ""), + (KernRe(r"^noinline +"), ""), + (KernRe(r"^__FORTIFY_INLINE +"), ""), + (KernRe(r"__init +"), ""), + (KernRe(r"__init_or_module +"), ""), + (KernRe(r"__deprecated +"), ""), + (KernRe(r"__flatten +"), ""), + (KernRe(r"__meminit +"), ""), + (KernRe(r"__must_check +"), ""), + (KernRe(r"__weak +"), ""), + (KernRe(r"__sched +"), ""), + (KernRe(r"_noprof"), ""), + (KernRe(r"__always_unused *"), ""), + (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""), + (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), = ""), + (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), + (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1= , \2"), + (KernRe(r"__no_context_analysis\s*"), ""), + (KernRe(r"__attribute_const__ +"), ""), + (CFunction("__cond_acquires"), ""), + (CFunction("__cond_releases"), ""), + (CFunction("__acquires"), ""), + (CFunction("__releases"), ""), + (CFunction("__must_hold"), ""), + (CFunction("__must_not_hold"), ""), + (CFunction("__must_hold_shared"), ""), + (CFunction("__cond_acquires_shared"), ""), + (CFunction("__acquires_shared"), ""), + (CFunction("__releases_shared"), ""), + (CFunction("__attribute__"), ""), + ] + + #: Transforms for variables + var_xforms =3D [ + (KernRe(r"__read_mostly"), ""), + (KernRe(r"__ro_after_init"), ""), + (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ""), + (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ""), + (KernRe(r"LIST_HEAD\(([\w_]+)\)"), r"struct list_head \1"), + (KernRe(r"(?://.*)$"), ""), + (KernRe(r"(?:/\*.*\*/)"), ""), + (KernRe(r";$"), ""), + ] --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 5B0B93590D1; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=TAu8twgfii/bda07ACGAGApLETArhIuCkBBnMgGmm6A+IU6KFhsCyy1YgxgSJS88frGPROVUOB6YvvmxtOJhMtLbjJFSI0Y6sOw+zS5UIHF8Vjy9I1d9wttlObqIb1b6IaKenwAiQshTiGNEAWFz7LTXnvI+VFuvGQkwFBynUF4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=I/r87jAWKSx+9k53qSEfwjXKAwqwD5/EwejaTkqMOBg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=CVh5rBv5qY+jifKVd8ITMMzztpVQkl0hCGBMxv1UrW2rmIPkL2655FSWihKuTOmgzU9gH29etjLTx9mswKE32C1/swSGE2DCbzUxkPCdFNzVMF0wpafEEG11iWq/ubJ398VXwhqtYD4ixOfNK/jYrs94T7TnCcV+/IzeLoWLUJc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Ls6wCREO; 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="Ls6wCREO" Received: by smtp.kernel.org (Postfix) with ESMTPSA id CE8C2C4AF17; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=I/r87jAWKSx+9k53qSEfwjXKAwqwD5/EwejaTkqMOBg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Ls6wCREOsdkPS2BTmCqVOWdk0RKi1xRFTee7pRAQWejzpXdGMH6S1Hh9Na1813ySw 26AORe9EZE7bUOTYNO0dMl3b1hsqYSZkM6Nsc8V8v50Y74yttswcOUv0cuFkGIdyJi aklMf1EzHWX0lj0jtHYhsJQOX+zKcc1cZEgwjbMckY2ydS+d3sz9dPsJpJ78bgvUJf RUtbk80zbUoz1VbLWqo1Oa6kRd1nhaSFxvk3BdQtxwUSVDXbSKq1XuVKBfKfhmvfdr j6qbCWbGDl0m7Uf9wbBqlBfjkHDTuUgqqfg06a41UeHtQ1NhP32rJxRWJwkWeWJdQk wisdK+HAXSpRg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVlX-0Eaz; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 27/41] docs: kdoc_re: don't remove the trailing ";" with NestedMatch Date: Sat, 31 Jan 2026 15:25:01 +0100 Message-ID: <68f663611c61411b0e638947347fb3b8f33c8630.1769867953.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 Removing it causes the parse to break some conversions, when NestedMatch is used on macros like __attribute__(). Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index a49b42e3d189..294051dbc050 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -358,10 +358,6 @@ class NestedMatch: =20 out +=3D new_sub =20 - # Drop end ';' if any - if pos < len(line) and line[pos] =3D=3D ';': - pos +=3D 1 - cur_pos =3D pos n +=3D 1 =20 --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 5DD8E3590D8; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=S3pwLa9O+qnPO16iR5XTJ/Ohc2pQilX0z+X63IlsPvv+sG0v6bEi7m7PtBgMPpHJZiw7oRLm/hDWUwfmbkVpRmqs08c4Vp0TFstZUBiQiWCDXzrJKnd1+dG2xiHvJiQl+4GKLYFy0UUzBBGwbfQaeMivpe5jDWeiGE4fxjiwGgs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=5oi2Tl2xWpO7qRnpBsDD+tLfzI2AZ4/vIG5DDw/7oQE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=OcWhYShW0/zWvE4si87D3OSW7mgSrsEqoj728lkI4yHCa+Ja6se8vnxX2L8Z4ve0KuW5BcvG8KeLXWo3VfUTA+Uo2Xt2R/vDjWgJqn0kDhCCv16pz9O46UWsXRJHuf5MQGHVwjfo4Z1cxakr5RH0D3zOpOzF6r3vYCIXSf7eI/M= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RVDclQXu; 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="RVDclQXu" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D0E27C4AF15; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=5oi2Tl2xWpO7qRnpBsDD+tLfzI2AZ4/vIG5DDw/7oQE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RVDclQXuAyozih8q+rZxUGbQC7kga7zXBPj1SQtLdXQMWOBq9vTCiHyP0yWfGjamY 5c5n6DO+c6X1qnQod2ReiapHWU7OxOmVYt1yuXnp0WNC+9oGBnyq9zGlHTcgZcar5j 0SXODn3RgFXvRob/iOywCjtwyB8TBH2hvU6xObs7hVKqsY7TCVlS8W5wptNwV48SEl LB/revnYGsJYy2PvLk2+IewUIYMCB5CQfCr0XHcJxKnYVkRpk9DTdDSWdv1eQZMhfU X6np2g1+sRpBF2X9ZiyfBre68WQvdaSntSCeTX96du5Ik58dbQUp3daI6QymqYeF/k uAjDiHjtc7GYg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVlb-0LvG; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 28/41] docs: kdoc_re: prevent adding whitespaces on sub replacements Date: Sat, 31 Jan 2026 15:25:02 +0100 Message-ID: <99fafea263739c19781c4e4d0dd2dbbd2c472df3.1769867953.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 294051dbc050..886e33ffd2b9 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -341,8 +341,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 @@ -365,7 +369,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 Sat Feb 7 17:55:25 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 6A0C4359F88; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=hf/7Eojp+sO5kNF1UFOYGCbOsAStSGT971b3ZmzN1OjmhJ/NahJbEoU0aj5VEqX9JCgOM0/kCHVcnpMI4NufIUwcBZBc8Yh/oo7fLVJgH4oOmTqavNCnXWO9HUXAZfiffyiN2Nqe4C0Z6mML6g82iEzETLCXaYhmFHPLBKE7K04= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=c78VBSuB3zJR1YCeHGb5UJcGA9b8DZwRfytxgWk/nVQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=paJnUAMntG6yxEOje+bkag+xHAkbE2eqlBetkzhDylg4xkle54EhJlvFxhdWax4h7vyISFVfrcvf7rSjKviYeCetyjkMiYXsiAf/Khxc8BRxhkCyt6+hNJpryjXEQk1F0N+i9G+PEIAmkK+plGtoJXJ4IMo1TayR6oN82ahUuiU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=FlayTHJs; 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="FlayTHJs" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D6D96C4AF1B; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=c78VBSuB3zJR1YCeHGb5UJcGA9b8DZwRfytxgWk/nVQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FlayTHJs2JUrQOYizmq+bu9LbW2w66UJVg9tbVq+HjdhRH0wnlriOKQ+ObL4grHnZ +r98L9a4ebz0IGwaVufND7ECK2QORhXbBvQVK5a+kMDa7qGwng3sDR4o0E+xDmh6Op VlmGodLkSbAOyoXmJxvDaIwuRmHzyOtGFbDIInKiTpzGbIK10Z0gzL/C6WkfT6FQTL Ppij1jr5RxAiEHQouiIYV7XVqh0HDtQumuNQ46hazfxSkW5WVTVX3lu2dcaOXH1KrM y3vvDQo+EnhPO+Mu8nbkXFfGeeANwYzVECJbdDObW/IbfycnsGRe0ICaCffV0Ut1G7 58BrPSt6HvYoA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVlf-0TIM; Sat, 31 Jan 2026 15:25:20 +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 , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 29/41] docs: xforms_lists.py: use CFuntion to handle all function macros Date: Sat, 31 Jan 2026 15:25:03 +0100 Message-ID: <4ad68fce80ea7f994665ce2d72b39f0098df2476.1769867953.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The new CFunction class handles better macros, as it works the same way C compilers do, handling delimiters tha right way. This allows removing complex regular expressions, placing instead just a simple one with the name(s) of the functions to be replaced. Doing a before/after check using "kernel-doc -man ." shows only cosmetic changes (whitespaces, mostly). Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/xforms_lists.py | 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 88968bafdb78..ea6520b38ea2 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 @@ -85,12 +72,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"), ""), @@ -108,9 +97,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 Sat Feb 7 17:55:25 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 62F8A3596ED; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=C9OxefML0YkzoFz+sbXLWTrto3t7R8ecMF8FcsbUN0iaNvvz2I41YXK0b6R8ZIi2jPtO45y4yjdOGYcQf58uN2vv265ZoPitnTcFR3FERJFOUqgiCcFQX96wNMwJELnB9bAM5ZtfI/Dq6zAKWdkPEDCPT9hXHQIITKRZv9PLU6A= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=3n5zkoFrFUOIWGD8NapCIbtnoFCw7B0BzF+EBvzaUy8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=gWSMovoNjRfEGQ+DU6ym9kl6CykgTCZT35xGu9Sv2ClLPCpuQMaCcoJ2xDZJe8AVtcc+8mkYdRoeQZqwTCGQwkDjH+f8ay5/8xnKGDqdkpxa+bR2cYxuVJS6YQgFzZ6raGA9onrpbg11TISH4UtSYYDKqccLr3Mju7iyuSmFa50= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=dHMXU/pk; 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="dHMXU/pk" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D6A65C4AF48; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869521; bh=3n5zkoFrFUOIWGD8NapCIbtnoFCw7B0BzF+EBvzaUy8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=dHMXU/pk4asVAvvkpHiG3eEJ5oA7riAKDCt3bzpKkOYdYUxfNrsNR73LYNJVGZuAU S8TXpfIoIBqt5UuHSafFQzct84M+zzW8u96y7Vw1vbNbAquzD6dvnE2qmeM75Afg6n xWdPbDEofdwioK5S71f/8SMHuxI4kCCY5uP/zsFstkvlsaq5Ec3TYOppshkcLZAF23 Inn3PDCwICFQoGtuh2TWzXrljwmhDiw5UpFOu6Vn1OIuWmG1cIBdiBdoqL1NwrqGkQ 9QjAAda+dkEIbjVqIzsJns52YoGLV+ASOJc8IN/6N1V4YKWhdDJQMwVCL76+vX4JQS bwP7h8SY6Wnew== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVlj-0aF2; Sat, 31 Jan 2026 15:25: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, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 30/41] docs: kdoc_files: allows the caller to use a different xforms class Date: Sat, 31 Jan 2026 15:25: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 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 Sat Feb 7 17:55:25 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 74BE6359FB8; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=Efownj+km/LgUsdaNtoYyHUualt/GBfekxGhlNnYC6FO2Dmv8ilFIm98iEf9oR9aZLHEVo9UPnqBareRuA34x8HsyclZHAZZNyk4gaNMUiD1ccrGWGjxUGD6ncPFMnuTKTm35h6eK3OjSvw4qMF3/DT5ZEZfhT5kneuDMIEQwEI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=ZDgtUhg2xj+M7eiW7ljRE3PrlESL14jiN0cCN9aIl+c=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=aunS0ROcIhAD3mznRfkBS2nIfMxNnTbXEWrRTi5twQb9D4NRyAeNOwyxZ0eeImfGzvHzigMRz/vOW+seNSwLVLEFL0e+U4IT6sknHzYdlCmzwR+ErdzwWWhgGLnwq0HHyH+u7qsc+nQdpImXaFWLBm6Ygd+hipouxgRSMb0007c= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=mElXao9y; 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="mElXao9y" Received: by smtp.kernel.org (Postfix) with ESMTPSA id E19B8C4AF5F; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869522; bh=ZDgtUhg2xj+M7eiW7ljRE3PrlESL14jiN0cCN9aIl+c=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=mElXao9y30lRlSfpVtg3eDT9wtAXjfGnpkDTDKoe7L5Ol/J9zWWyaPRjl6FMGl/hS PMRQFW2NrYPDGbhoOyZd0RnmHVSOctMhQx3ZZOn1b2OHrh0xvTYKGPq6zFsWh4q5N8 JxfowYerQf7tcIjQLaPz+9C+UD++YeKeBkS3mzQtBOFvIEcOolGenu/C26lSdUp/6u +t0OI3hXqZzbzZXKg0QrRaUHEK34jZ+c+XoZIt+nCfuEXPj7zOz0NAuqQFFAbhOpIE z9b9KaCdLxwp4sgFRd3/leU3c2swVljHE2LoKoEYmibadeYizGwhwXZNHS+ngpQJcl UalErO7YsO7jA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVln-0hEO; Sat, 31 Jan 2026 15:25: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 , Mauro Carvalho Chehab , Randy Dunlap , Akira Yokosawa Subject: [PATCH v4 31/41] docs: kdoc_re: Fix NestedMatch.sub() which causes PDF builds to break Date: Sat, 31 Jan 2026 15:25:05 +0100 Message-ID: <47bbc4753235edb31c9faec00bfa790f798a2ca0.1769867953.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 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 | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 886e33ffd2b9..f67ebe86c458 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -323,19 +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 r'\0' is used, it works on a similar way of using re.group(0): - it places the entire args of the matched paired data, with the - delimiter stripped. + ``\{0}`` is a special case that expands to the entire matched = text. =20 - If count is different than zero, it will replace at most count - items. + ``line`` + The string to operate on. + + ``delim`` + The delimiter used by identify the placeholder groups + (defaults to ","). + + ``count`` + Maximum number of replacements per match. If 0 or omitted, + all matches are replaced. """ out =3D "" =20 @@ -355,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 Sat Feb 7 17:55:25 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 749CC359FAF; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=CmbQZiQe0EcCcPv+U49bmZqqi+Sa30H7s6yDATlO9SBaDe2HKzDdBB6mgZtOHaLv0r/6qCFaZakBPhJXNb2HWHyUFcgcFNcIZ+2uoOSLuZ0HsJBNkuzO3RQPcXDi3ych/fACSbDba+VGEJv6plCi6Htpw0DJf+q7RJaaJkhLkcg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=4aMfKYcVERhHxWAsYjEi8+tgICvrID1mZsAmSUTyoxc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=th9Tign/ogcZUgLi3jjfBzw97d8T2X1DpH9VRj/qxpnqtvC0BPGVWc8U14fDxSiUg0OdM35aUEfcbvF8QJoBn0KatSC0YxWOCetMZMKdEjugVqgdX672sV0qsyu+9Bgd2GznMqiM+hPZDXpT+0NMON1gaiwa5pE/Rqb9rI6JKqE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=GwEnvRTB; 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="GwEnvRTB" Received: by smtp.kernel.org (Postfix) with ESMTPSA id E75FEC4CEF1; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869522; bh=4aMfKYcVERhHxWAsYjEi8+tgICvrID1mZsAmSUTyoxc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GwEnvRTBbcukjFCvBXvPdgcMk8cgUg/NaCFQ0rJOvDeTecyO+ZPAkjpB/Ku3JxiY8 GMBLmijNIKMU44tEeKWSwefOeYvvim8vyZpfqFsjJMPO27NfrgSeVMkDacZNKm60Cb XNLdkazVD4yre6r7b0aF1is/lkAwGwRGaMrdozz4fvmF7zDzMfTsOM4TI6kuu2Slbq HzMCVXVkDYQh+J+b9YGeyPpOtOwVbT/ma64oMzW8R51OIxHD7f2f8KzCF9jzsjf+ZK Yy7GXjlkf9Owx8xrNBMDZGTq6Wzv4s0SsQNowqDsocRn2CoCKudSeOONO5uwmZbHCx 3ZESXL3Kdrumg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVlr-0oEC; Sat, 31 Jan 2026 15:25:20 +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, Randy Dunlap , Shuah Khan Subject: [PATCH v4 32/41] docs: sphinx-build-wrapper: allow -v override -q Date: Sat, 31 Jan 2026 15:25:06 +0100 Message-ID: <64fe15e0ddaba7de59a7c031db03f87c19873c04.1769867954.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 Documentation builds were using "-q" for a long time, but sometimes it is nice to see the Sphinx progress, without increasing build verbosity - which would also turn on kernel-doc verbosity. Instead of doing that, let's parse the sphinx-build already-existing -v: each time it is used, it increases the verbosity level. With that, if the default is to use -q, a single -v will disable quiet mode. Passing more -v will keep increasing its verbosity. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/sphinx-build-wrapper | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index 78ff7ac202ef..8080ace60680 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -168,6 +168,7 @@ class SphinxBuilder: parser =3D argparse.ArgumentParser() parser.add_argument('-j', '--jobs', type=3Dint) parser.add_argument('-q', '--quiet', action=3D'store_true') + parser.add_argument('-v', '--verbose', default=3D0, action=3D'coun= t') =20 # # Other sphinx-build arguments go as-is, so place them @@ -179,10 +180,14 @@ class SphinxBuilder: # Build a list of sphinx args, honoring verbosity here if specified # =20 - verbose =3D self.verbose sphinx_args, self.sphinxopts =3D parser.parse_known_args(sphinxopt= s) + + verbose =3D sphinx_args.verbose + if self.verbose: + verbose +=3D 1 + if sphinx_args.quiet is True: - verbose =3D False + verbose =3D 0 =20 # # If the user explicitly sets "-j" at command line, use it. @@ -195,8 +200,11 @@ class SphinxBuilder: else: self.n_jobs =3D None =20 - if not verbose: + if verbose < 1: self.sphinxopts +=3D ["-q"] + else: + for i in range(1, sphinx_args.verbose): + self.sphinxopts +=3D ["-v"] =20 def __init__(self, builddir, venv=3DNone, verbose=3DFalse, n_jobs=3DNo= ne, interactive=3DNone): --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 88CC835A93B; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=Z1V2qWONqM4HChq0CxOUihiQy/OaO9KJ92p73XB8++aU7r/4s6panXOf8V3f43oJIe5H9askYBHDhOxfKPOmd3CqqnUv0geKChUMZAAJY4TbqUnsElGJGvrLzSe2QDIGKEcM29WmmwgxkphtW6SDpNoW03397xHPQGP4FyvyHqI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=C2cStPoOoGCftK6fYM/VQjKEO1UC2wtJ9483nmjaklU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=cEOfetqAl1XlXVsZlqdJHNBO6Eqeu/fodY7hFQ6jhgWaS0MS2gGzJtLf5rYihITKGnIY7ly0QSiEQJLKDQ/REILIU+C3nS+ZFtl7DO5vmn34BPXvda5eohjeLJLY4Ojy+nsE3sJe5HrTLgxZykh0KfRz0Ra/ZjhkOHR9W6f4vy8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=XUlq74Q3; 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="XUlq74Q3" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 04926C4AF67; Sat, 31 Jan 2026 14:25:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869522; bh=C2cStPoOoGCftK6fYM/VQjKEO1UC2wtJ9483nmjaklU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XUlq74Q3cKfYzyY2KmtaeWNQkjLbbRDt5JtA5d4kbIkyhkSG2+r9AGrHLU4Qs3OAO 3CImQgNMNaRltbbsjangUr8/RFy/xKGsHu358A75l53bxFqHHyasF1Y45xDrcFc7ZZ zUGz4lPK3g2E73Jcj6dtY4eaNtIuN0oRlF39s22PGLYoBlu/2KrKfAQvAhr+IyXRR+ fiDNVldhW85MRQCVRgbBHJVmTVarAAtjw7rDnTFIEHavj+WTvsWpLmLJ87yKpKiD0Q +HIoB2dNIDt/n0P2oHfuEaY5mV8k8GNS3pw9TsRmf1W18wyoLE9yQyFvxtldDB8Ism kso7P7jRnB1bA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVlv-0v7X; Sat, 31 Jan 2026 15:25: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, Mauro Carvalho Chehab , Randy Dunlap , Shuah Khan Subject: [PATCH v4 33/41] tools: sphinx-build-wrapper: improve its help message Date: Sat, 31 Jan 2026 15:25:07 +0100 Message-ID: <9a41e5aa1da74e30a05bc21537a0c170450f01e3.1769867954.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 Besides the parameters that are passed via command line arguments, the wrapper's behavior is affected by several environment variables. Document that. While here, use __doc__ for its description. Signed-off-by: Mauro Carvalho Chehab --- tools/docs/sphinx-build-wrapper | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index 8080ace60680..b7c149dff06b 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -814,20 +814,42 @@ def jobs_type(value): except ValueError: raise argparse.ArgumentTypeError(f"Must be 'auto' or positive inte= ger, got {value}") # pylint: disable=3DW0707 =20 +EPILOG=3D""" +Besides the command line arguments, several environment variables affect i= ts +default behavior, meant to be used when called via Kernel Makefile: + +- KERNELVERSION: Kernel major version +- KERNELRELEASE: Kernel release +- KBUILD_VERBOSE: Contains the value of "make V=3D[0|1] variable. + When V=3D0 (KBUILD_VERBOSE=3D0), sets verbose level to "= -q". +- SPHINXBUILD: Documentation build tool (default: "sphinx-build"). +- SPHINXOPTS: Extra options pased to SPHINXBUILD + (default: "-j auto" and "-q" if KBUILD_VERBOSE=3D0). + The "-v" flag can be used to increase verbosity. + If V=3D0, the first "-v" will drop "-q". +- PYTHON3: Python command to run SPHINXBUILD +- PDFLATEX: LaTeX PDF engine. (default: "xelatex") +- LATEXOPTS: Optional set of command line arguments to the LaTeX engi= ne +- srctree: Location of the Kernel root directory (default: "."). + +""" + def main(): """ Main function. The only mandatory argument is the target. If not specified, the other arguments will use default values if not specified at os.environ. """ - parser =3D argparse.ArgumentParser(description=3D"Kernel documentation= builder") + parser =3D argparse.ArgumentParser(formatter_class=3Dargparse.RawTextH= elpFormatter, + description=3D__doc__, + epilog=3DEPILOG) =20 parser.add_argument("target", choices=3Dlist(TARGETS.keys()), help=3D"Documentation target to build") parser.add_argument("--sphinxdirs", nargs=3D"+", help=3D"Specific directories to build") parser.add_argument("--builddir", default=3D"output", - help=3D"Sphinx configuration file") + help=3D"Sphinx configuration file (default: %(defa= ult)s)") =20 parser.add_argument("--theme", help=3D"Sphinx theme to use") =20 @@ -843,7 +865,7 @@ def main(): help=3D"place build in verbose mode") =20 parser.add_argument('-j', '--jobs', type=3Djobs_type, - help=3D"Sets number of jobs to use with sphinx-bui= ld") + help=3D"Sets number of jobs to use with sphinx-bui= ld(default: auto)") =20 parser.add_argument('-i', '--interactive', action=3D'store_true', help=3D"Change latex default to run in interactive= mode") --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 8211235A933; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=mFYx+Vxj1Jp0C1IL1X3jvWGYLaTbDE6y75v5RD1a+7SfUGxtoeiQeASrt0HhFIS9j5cBX1+g04v84rZvnMRwXh7Lsd0opcbacLDEZVD8vr5BPSxOawWlIdoNgrgfsZUSzajZpwOWfZKrbGC888BKpzXkIvGyOTas7j2da8Ztmjk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=93FI6HCbFuKLoTGysvIesP/671jVJYX05qdlxtKR9Kk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=lv8Bsp4uR0rIb+9k+MVlxAXmI1rVp76A6robz6Q6jBkjmsqA4tSGyTbzf/qftyxKQPVvBUrmz3q2cRQYu1Y6zsEfdfaMSIDH/untHH+9tqTE3yz3eVVUAtEpqMji1vy1Y/mlkzRzUifxgki9xuVBj0W+Csp/4Z6xvlf+W/RDTts= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=SqYzYt4I; 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="SqYzYt4I" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 03990C4AF64; Sat, 31 Jan 2026 14:25:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869522; bh=93FI6HCbFuKLoTGysvIesP/671jVJYX05qdlxtKR9Kk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=SqYzYt4IVbQPk0+jVuZ5Mhm77EzcOYeCDYr1W2HuJd8hXnAxnVEJQ8JMaAIBj6hDK F9ld/mXQMtTt6G+oCP/+SOwNUStMoI62trzL72ps7dw3/2PBRffb/epek6i+75z9Wo sw4shcSs4yVNiPTU/KitBkVX6jiSrQKT3by6VGT9JLow1pCHB/xI615IOPPlwhv+S9 ZTnQTEIGjPQZ8CPMO+MKH+8LP+9uC1b2j1P0P/+UCCa+2G8evst/yofLjr2xolWBwa NSAD99xusS4nq3x5iW/Wvjx6ul+7/wgQFUyHaNSK6Y4u6n1IcPC+t8lH3OJrGuxYJm AAWAO5q9fQ7JA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVlz-11Zm; Sat, 31 Jan 2026 15:25: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, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 34/41] docs: kdoc_files: document KernelFiles() ABI Date: Sat, 31 Jan 2026 15:25:08 +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 Sat Feb 7 17:55:25 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 7E14235A92E; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=ebpiml8y0/ltUxmzZOQ0jcs0cXAoM4NVT4RhPkHGngicZbH8wD4uJHGIDzzRbFh4GHeKtqRGDo0lvKsSFH/GYk67ZKy/+/3Rng+uhJYgyuThwpbuRO0NJca83fXOnW/tFPcXv0VzjDG26Q6psoSDXSQKg4mVhJIwB1fSfzs5r/w= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=CwHsRCLR3wmM4G7G9vnHWInI3q03RKTr8dBQN45i3sE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=u6cOn+UEkxD4vj2E0T0ml65BUizI/HyZx++4wLU9QXZ4IX7l+gq3NKK6sOxF9ChPy6StTRAWIk37FPU7CS2235Socrkqi9QuGvr4dgLF6Y1K3aQJVOp1+Jh/TsVCc7dMNGv2cMxvROWbkmIFs16E0ilAbQF3uo5lL5pKbwzxZhE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=uJrxdO8o; 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="uJrxdO8o" Received: by smtp.kernel.org (Postfix) with ESMTPSA id F2D87C4AF62; Sat, 31 Jan 2026 14:25:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869522; bh=CwHsRCLR3wmM4G7G9vnHWInI3q03RKTr8dBQN45i3sE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uJrxdO8oCa5P9y9iP18SyDLyWn9DYbKIpv1VOzITG4adEF/ptMevl3UgwnAE//lVc Q8bDOHbZSJyfxxuIpJd4pLvsc6yB+sxECrSZ3gyjdmTWTC6vmTWZg3Ax892X2Ir8Gu 5i7vP/mlwUp3Bud8QXeQWUJ3f4DpX+bUDlCRmneYEPossKeZ5Lupi0jhwm1ikBYojH vu1wxcD4wUdrVPjMLv0J/EZ5/pkbP9WO2inGFsaxQmckbr+wEQQtuPM0qkw0qWBaf5 Vo93bnPrZDKSymLfiGB+RJpjeTc6/MRfayCi0IxPq0TjP85UD5eE32IlyrSBe4mFA0 +mygCXG+hGKQw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVm3-18Hs; Sat, 31 Jan 2026 15:25: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, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 35/41] docs: kdoc_output: add optional args to ManOutput class Date: Sat, 31 Jan 2026 15:25:09 +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 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 Sat Feb 7 17:55:25 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 86FF435A939; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=p6ycvzFYgw7bRVloHzXTSCiru1Q+apx101GzcXXY1a5TdXdPo2Yym/RwUdBMO3DktknvkPoov1SDUhEq9CRy0cSiYnWl8mFl/5iTYq+rHIB+WArYY1EAKcqNMKYO86E2kZ1Rm7rVk8bfc3pNeSZ6OFoyuuAmvKyle8duYLIFURs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=J9gpBcUhWSmksHEje7HfFrvd/UJKiZjrUhxoxqAfK3o=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=nxJB30JKScPypBtBN4EDPcpC77+oqphn5qrBCPT5EiJykYRPS7a2s1YjbhDjV+Iq1xeBp3j3tkEPFA/sDJpdWsyaO0jiZb4ufsWpFcjW1qPTl7T2nzaAQO7mH35lSFHZYegGqke7ZGJlX/koIy9bLjZmBacvPpGgR5E+nYWmOd4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=etJT7UQk; 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="etJT7UQk" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 0AE0AC4DDE2; Sat, 31 Jan 2026 14:25:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869522; bh=J9gpBcUhWSmksHEje7HfFrvd/UJKiZjrUhxoxqAfK3o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=etJT7UQkV81clZC3G9h1rJ6n/Coqg5VDtA8GfexHi9ncJVJvmpBQn1iDvm2eAuBhd Fj2wqeMsPUTEWk9IWBwYb7NqerSM4TNrTRMxWYPUk7i181CDG8Gi7dOnc3eOZ24S0X h1Z4uZMcX8n+nsH0YSf0+ou5Y+ltihG+SwY/lHVlE0E/JmJyjrHO4O2jsrAHbuRtPA rmuphAK/iswiSm/1w46YZxxM8R7TX0lmY6q9CKMz7x188BBO3DQlNRe0dm7aCy16zZ /5ICALjF/4Z/ZMxwm6EtuGqjEOym6sXbhoG/WTbzLDMJ08JaKg/9CVMtBUVXBc3OmR 5GBDzj4RSnRIw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVm7-1FNc; Sat, 31 Jan 2026 15:25:20 +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, Randy Dunlap , Shuah Khan Subject: [PATCH v4 36/41] docs: sphinx-build-wrapper: better handle troff .TH markups Date: Sat, 31 Jan 2026 15:25:10 +0100 Message-ID: <56468f3cf9ba583a0759953a931bddc361b869aa.1769867954.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 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 Sat Feb 7 17:55:25 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 9025035A945; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=dZag052rToNTID6UYD6A6E7Tp5NniTy4JKU12xrpJCcASZwwgyxJSiO1CDgJ5a7qq3VROpWij1enOM1IkV9x1wItpIHMckhmeD9m5K/ICJulmGBwoC95LdDNyALrhR2PaJO7iCQ/KHb/k+rVEnpivjTZsuF++y8eRMnpndSto0M= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=xc3bdeTKA4gaQTm1QPUjzckBF1/Bc6XutKPIezxeXB8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=IPlDmiUU88UUmvIyTZKxT0f6yBhLhvI6AhU+o5STtmJdh3DTnIimVlZz2jqGvgn0OhnO8gTKq1LMX5Rth7k+75OssP4LJLPZpC7ySlNngSbtS7rizeITnnL2eZ+EKpepwwuEPvCVgjIkz8wV8vnQbTtkXGey3+VFMLziebpTdvY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=e+lgoG9C; 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="e+lgoG9C" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1600DC2BD04; Sat, 31 Jan 2026 14:25:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869522; bh=xc3bdeTKA4gaQTm1QPUjzckBF1/Bc6XutKPIezxeXB8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=e+lgoG9CCnr7rpRrfsny4rjU3fOjEA51AuUGLbiRKwx4JxSMtmKdWklJMdOrLCagH JF5wdiKyo3olj2bQCU/JKO4RWNPvW5PiF38+1ed3tFZVgSB6VxYq7mXw5iNUgROa9S f2AqXDqsVXQKNJAnTON850mtt7wlHtt6Q00qG5g9KlvTCRkHgxbsgj/Ag22zWTaXeT aUo438xrkfrN2S8hpQFTeJ0cPbJZfK6PMPnw486vZ72kMUbNXYGXODLNQcTQqAeIhP 0yiQUASDOOvdYUZeyMG0irPKAvFiWPIWSvNVWbbf9wn9hQpeZ7Hu2CHivgMnC22av+ kONely4AuJDNw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVmB-1Mc4; Sat, 31 Jan 2026 15:25: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, Mauro Carvalho Chehab , Randy Dunlap , Shuah Khan Subject: [PATCH v4 37/41] docs: kdoc_output: use a more standard order for .TH on man pages Date: Sat, 31 Jan 2026 15:25:11 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab 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 Sat Feb 7 17:55:25 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 8F81B35A943; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=Q0KMkjzR6Y8jcCpX5eZAQVyn+PC3ZapfgM+Ve1AwUsPYwc/kzB9peUNJdipqdZbbSeOcMBQ6f/9A83Yk2HVGTPNGa9QBiQ3T2XdEaEhGeu0GIMxLj5bW4Q+D45ea4F0o9VKLSRbiJDgNQfAXDrQKEQK/SR8rlgWM1x97RZi4OcM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=3P9hiqMJWs99bANIe05s+PiDHBtg0dmIB/Ud7yaibWo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=k2iwp69paW4KmyvXLRWGMlutfIO3mybUPny4S9P4QOHKzN3f7su0wHlfh6K4wyQYIVNpI98r+NOMtHcazC4/6OhpEUK20Ba521mOh1ZSpiGsMxILMoT6g91xPmqCIgZqGTWwyzXkrzHMVPQreqomKcmORhzS78sVISh72jZ8BSo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=gWMvSLN2; 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="gWMvSLN2" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 19BD9C4DDE8; Sat, 31 Jan 2026 14:25:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869522; bh=3P9hiqMJWs99bANIe05s+PiDHBtg0dmIB/Ud7yaibWo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gWMvSLN2ujlPPfqzEcYYm3pAFHIatlR6wb6AcOiZ2qVO+R7A7nbl+sESP4AIpfstD wfjtcvHyboTY8AjB/f+BZVAYgC5KZU0s6C/EHNiexVcFM9n+0EnUQzWvgHr2yoiVJl v6Qnv8t5jP5qZ2yHt9Viiym0N985MHwV3ogYAZ9/qSkV5SO4kWElv2/8R1C8XTRolK x1UvOZHahwuyB6QWiGWpIYX1YDtcLo0Lq5qSEY+sUTbcO8uN0C0Ifrww64WBi3d9l7 W8iF5jf6pO8iOT9qZ2qvp/X4klGpMkTeUgnotDqMbX7Mq6XkbfEYIMhZ3C6fsonMMI cMdz/SRhqTQeQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVmF-1Tb5; Sat, 31 Jan 2026 15:25: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, Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 38/41] docs: kdoc_output: describe the class init parameters Date: Sat, 31 Jan 2026 15:25:12 +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 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 Sat Feb 7 17:55:25 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 92F2D35A94B; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=oxUM7S21Odem+QJqDTGlTz7jjAFSOhW/ZjByg1JPwGnLNybb7PU3+hk4d0405R28q01IqvHQxwr1P63ZwL3KT/BO3MKaFokSiNXlUqryaFllgdpZq7EiFVI9JYA3deHQv/78FCSTLFH19EEeYPi7sdk8A65ARTJDNawCzNKa+u4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=fvMjJpvYeiR5dsEmac23+IArGmOBOLOmIiyyzQVBvqE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ik9uVQrx6/xkd8sCA5fAGggc1jVAK6Ue+gI/lF/tbbgWVa96QVwPOjhFRIhwBd9YQaBKmUxTbOU/OGEhNaeMv/dl6eH/+H/oG28+v5x4YybOPMAaHHpbEAwUhUZEeQynXTDr2BQ/Lt7iMHr1Ip4iNoO/GC8ulF6H0Rqv/0DFdPI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=XxgdspMd; 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="XxgdspMd" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1C08FC2BD05; Sat, 31 Jan 2026 14:25:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869522; bh=fvMjJpvYeiR5dsEmac23+IArGmOBOLOmIiyyzQVBvqE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XxgdspMdj4pmCSN5G242JuUUWCeu7qsVmXwqQ5luBBhXV+IIqMD587xXrGfXFUfsF tDxNWQvnSDcIDoDNZmohLcgq8na8es/trtxx7rzvrc4gf5w0wcMkWAeVPtBlqOIVow sm3xNSkA0iixlMEw1YTEyBG1s5E3GDuLnlDk7IR0JJGZD0072klw04EJwtuMPpNxxe AdtOEugT5Kc1o2iC1rNMPJytYLxuourKKTPkt7qzrVYN6F/ubvDXPCYYzOoYk9UzLc Okky32I8fXWyqpNWBYOHGiSdz5FnT2C8MoF9UCMB07DpV4TVit3vafoCnvA5tKm8jK lPZW8/sxNw9Bg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVmJ-1akZ; Sat, 31 Jan 2026 15:25:20 +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, Randy Dunlap , Shuah Khan Subject: [PATCH v4 39/41] docs: kdoc_output: pick a better default for modulename Date: Sat, 31 Jan 2026 15:25:13 +0100 Message-ID: <9bf76cd7412f49f0cf8628ceb3ebb2e1535d9d4c.1769867954.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 From nobody Sat Feb 7 17:55:25 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 A9DE535B638; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=FuWEdT441tzclI/Mq/NQPYVrhS/X6u8EciedPxffAfTqG2Rq6tQqNFvXTeB+VULI+GfGFK70aH47kwVHmnQt6w3LXce6zf2+bsCx0L4KuJpF4+O0WasbDB3xvZhKGVLl1PgV5nc5EHEtZvLN34rpcuuomI8X9OHd35SVCpojCSE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=JgAESjeyMdGBTP/DT74Q19UkIkpbBQsD4O6RYrpw4MQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ZuTGCed9RDlz2hO8e/NSNrdP8hHIIzwTlTnaaRtzHe8cbKoPRqV+CWYCeo11hf13KdZU1W1wyxf/4tjeHsHjMp4R6B5bj3VNVXIiR6+E8Ryp1nW3Ae0WjsGGmMX5AS+zAp8ACOvpkohA0/30eYs7UCuQ+SyYDvczl7eRpaUtSR4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=FWjwGdDD; 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="FWjwGdDD" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2BFFCC2BCAF; Sat, 31 Jan 2026 14:25:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869522; bh=JgAESjeyMdGBTP/DT74Q19UkIkpbBQsD4O6RYrpw4MQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FWjwGdDDFTueSCv2dGBxIxcKTvz6ucwoQyWv2j0Enk5xwhFFzMr/Ai1X7nhp7J0Zn KUZWXHrUjbulh7pnOD45vi2mjdH9u1F+3y55NKPPkrYzNy4Svo+LXOhE95ucYTCkqs zm4i6CzQop1iYv6z8oZ8TnQOhSk/9BLdRXK06mDyPMJnjoIWWrE8MBP43XiAHGqFlT sVOK8sBbmRg991tJEBDsw1JPHerSy4TVVL3/W1Lm52j+xgKTOMWxuYO30ST/Bj8CoK tIyYF3hyUU0JvsJ+CCR7VWRAzO/+o1rg53sCKQ57wQ0PxRSyOm/afznVCo5F8higx+ OCD2IcsBZSeGA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVmN-1hvH; Sat, 31 Jan 2026 15:25: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, Mauro Carvalho Chehab , Randy Dunlap , Shuah Khan Subject: [PATCH v4 40/41] docs: python: add helpers to run unit tests Date: Sat, 31 Jan 2026 15:25:14 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab While python internal libraries have support for unit tests, its output is not nice. Add a helper module to improve its output. I wrote this module last year while testing some scripts I used internally. The initial skeleton was generated with the help of LLM tools, but it was higly modified to ensure that it will work as I would expect. Signed-off-by: Mauro Carvalho Chehab --- Documentation/tools/python.rst | 2 + Documentation/tools/unittest.rst | 24 ++ tools/lib/python/unittest_helper.py | 348 ++++++++++++++++++++++++++++ 3 files changed, 374 insertions(+) create mode 100644 Documentation/tools/unittest.rst create mode 100755 tools/lib/python/unittest_helper.py diff --git a/Documentation/tools/python.rst b/Documentation/tools/python.rst index 1444c1816735..3b7299161f20 100644 --- a/Documentation/tools/python.rst +++ b/Documentation/tools/python.rst @@ -11,3 +11,5 @@ Python libraries feat kdoc kabi + + unittest diff --git a/Documentation/tools/unittest.rst b/Documentation/tools/unittes= t.rst new file mode 100644 index 000000000000..14a2b2a65236 --- /dev/null +++ b/Documentation/tools/unittest.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Python unittest +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Checking consistency of python modules can be complex. Sometimes, it is +useful to define a set of unit tests to help checking them. + +While the actual test implementation is usecase dependent, Python already +provides a standard way to add unit tests by using ``import unittest``. + +Using such class, requires setting up a test suite. Also, the default form= at +is a little bit ackward. To improve it and provide a more uniform way to +report errors, some unittest classes and functions are defined. + + +Unittest helper module +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. automodule:: lib.python.unittest_helper + :members: + :show-inheritance: + :undoc-members: diff --git a/tools/lib/python/unittest_helper.py b/tools/lib/python/unittes= t_helper.py new file mode 100755 index 000000000000..d2efb78d8561 --- /dev/null +++ b/tools/lib/python/unittest_helper.py @@ -0,0 +1,348 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright(c) 2025-2026: Mauro Carvalho Chehab . +# +# pylint: disable=3DC0103,R0912,R0914,E1101 + +""" +Provides helper functions and classes execute python unit tests. + +Those help functions provide a nice colored output summary of each +executed test and, when a test fails, it shows the different in diff +format when running in verbose mode, like:: + + $ tools/unittests/nested_match.py -v + ... + Traceback (most recent call last): + File "/new_devel/docs/tools/unittests/nested_match.py", line 69, in te= st_count_limit + self.assertEqual(replaced, "bar(a); bar(b); foo(c)") + ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + AssertionError: 'bar(a) foo(b); foo(c)' !=3D 'bar(a); bar(b); foo(c)' + - bar(a) foo(b); foo(c) + ? ^^^^ + + bar(a); bar(b); foo(c) + ? ^^^^^ + ... + +It also allows filtering what tests will be executed via ``-k`` parameter. + +Typical usage is to do:: + + from unittest_helper import run_unittest + ... + + if __name__ =3D=3D "__main__": + run_unittest(__file__) + +If passing arguments is needed, on a more complex scenario, it can be +used like on this example:: + + from unittest_helper import TestUnits, run_unittest + ... + env =3D {'sudo': ""} + ... + if __name__ =3D=3D "__main__": + runner =3D TestUnits() + base_parser =3D runner.parse_args() + base_parser.add_argument('--sudo', action=3D'store_true', + help=3D'Enable tests requiring sudo privil= eges') + + args =3D base_parser.parse_args() + + # Update module-level flag + if args.sudo: + env['sudo'] =3D "1" + + # Run tests with customized arguments + runner.run(__file__, parser=3Dbase_parser, args=3Dargs, env=3Denv) +""" + +import argparse +import atexit +import os +import re +import unittest +import sys + +from unittest.mock import patch + + +class Summary(unittest.TestResult): + """ + Overrides ``unittest.TestResult`` class to provide a nice colored + summary. When in verbose mode, displays actual/expected difference in + unified diff format. + """ + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + + #: Dictionary to store organized test results. + self.test_results =3D {} + + #: max length of the test names. + self.max_name_length =3D 0 + + def startTest(self, test): + super().startTest(test) + test_id =3D test.id() + parts =3D test_id.split(".") + + # Extract module, class, and method names + if len(parts) >=3D 3: + module_name =3D parts[-3] + else: + module_name =3D "" + if len(parts) >=3D 2: + class_name =3D parts[-2] + else: + class_name =3D "" + + method_name =3D parts[-1] + + # Build the hierarchical structure + if module_name not in self.test_results: + self.test_results[module_name] =3D {} + + if class_name not in self.test_results[module_name]: + self.test_results[module_name][class_name] =3D [] + + # Track maximum test name length for alignment + display_name =3D f"{method_name}:" + + self.max_name_length =3D max(len(display_name), self.max_name_leng= th) + + def _record_test(self, test, status): + test_id =3D test.id() + parts =3D test_id.split(".") + if len(parts) >=3D 3: + module_name =3D parts[-3] + else: + module_name =3D "" + if len(parts) >=3D 2: + class_name =3D parts[-2] + else: + class_name =3D "" + method_name =3D parts[-1] + self.test_results[module_name][class_name].append((method_name, st= atus)) + + def addSuccess(self, test): + super().addSuccess(test) + self._record_test(test, "OK") + + def addFailure(self, test, err): + super().addFailure(test, err) + self._record_test(test, "FAIL") + + def addError(self, test, err): + super().addError(test, err) + self._record_test(test, "ERROR") + + def addSkip(self, test, reason): + super().addSkip(test, reason) + self._record_test(test, f"SKIP ({reason})") + + def printResults(self): + """ + Print results using colors if tty. + """ + # Check for ANSI color support + use_color =3D sys.stdout.isatty() + COLORS =3D { + "OK": "\033[32m", # Green + "FAIL": "\033[31m", # Red + "SKIP": "\033[1;33m", # Yellow + "PARTIAL": "\033[33m", # Orange + "EXPECTED_FAIL": "\033[36m", # Cyan + "reset": "\033[0m", # Reset to default terminal col= or + } + if not use_color: + for c in COLORS: + COLORS[c] =3D "" + + # Calculate maximum test name length + if not self.test_results: + return + try: + lengths =3D [] + for module in self.test_results.values(): + for tests in module.values(): + for test_name, _ in tests: + lengths.append(len(test_name) + 1) # +1 for colon + max_length =3D max(lengths) + 2 # Additional padding + except ValueError: + sys.exit("Test list is empty") + + # Print results + for module_name, classes in self.test_results.items(): + print(f"{module_name}:") + for class_name, tests in classes.items(): + print(f" {class_name}:") + for test_name, status in tests: + # Get base status without reason for SKIP + if status.startswith("SKIP"): + status_code =3D status.split()[0] + else: + status_code =3D status + color =3D COLORS.get(status_code, "") + print( + f" {test_name + ':':<{max_length}}{color}{s= tatus}{COLORS['reset']}" + ) + print() + + # Print summary + print(f"\nRan {self.testsRun} tests", end=3D"") + if hasattr(self, "timeTaken"): + print(f" in {self.timeTaken:.3f}s", end=3D"") + print() + + if not self.wasSuccessful(): + print(f"\n{COLORS['FAIL']}FAILED (", end=3D"") + failures =3D getattr(self, "failures", []) + errors =3D getattr(self, "errors", []) + if failures: + print(f"failures=3D{len(failures)}", end=3D"") + if errors: + if failures: + print(", ", end=3D"") + print(f"errors=3D{len(errors)}", end=3D"") + print(f"){COLORS['reset']}") + + +def flatten_suite(suite): + """Flatten test suite hierarchy.""" + tests =3D [] + for item in suite: + if isinstance(item, unittest.TestSuite): + tests.extend(flatten_suite(item)) + else: + tests.append(item) + return tests + + +class TestUnits: + """ + Helper class to set verbosity level. + + This class discover test files, import its unittest classes and + executes the test on it. + """ + def parse_args(self): + """Returns a parser for command line arguments.""" + parser =3D argparse.ArgumentParser(description=3D"Test runner with= regex filtering") + parser.add_argument("-v", "--verbose", action=3D"count", default= =3D1) + parser.add_argument("-f", "--failfast", action=3D"store_true") + parser.add_argument("-k", "--keyword", + help=3D"Regex pattern to filter test methods") + return parser + + def run(self, caller_file=3DNone, pattern=3DNone, + suite=3DNone, parser=3DNone, args=3DNone, env=3DNone): + """ + Execute all tests from the unity test file. + + It contains several optional parameters: + + ``caller_file``: + - name of the file that contains test. + + typical usage is to place __file__ at the caller test, e.g.= :: + + if __name__ =3D=3D "__main__": + TestUnits().run(__file__) + + ``pattern``: + - optional pattern to match multiple file names. Defaults + to basename of ``caller_file``. + + ``suite``: + - an unittest suite initialized by the caller using + ``unittest.TestLoader().discover()``. + + ``parser``: + - an argparse parser. If not defined, this helper will create + one. + + ``args``: + - an ``argparse.Namespace`` data filled by the caller. + + ``env``: + - environment variables that will be passed to the test suite + + At least ``caller_file`` or ``suite`` must be used, otherwise a + ``TypeError`` will be raised. + """ + if not args: + if not parser: + parser =3D self.parse_args() + args =3D parser.parse_args() + + if not caller_file and not suite: + raise TypeError("Either caller_file or suite is needed at Test= Units") + + if env: + patcher =3D patch.dict(os.environ, env) + patcher.start() + # ensure it gets stopped after + atexit.register(patcher.stop) + + verbose =3D args.verbose + + if verbose >=3D 2: + unittest.TextTestRunner(verbosity=3Dverbose).run =3D lambda su= ite: suite + + # Load ONLY tests from the calling file + if not suite: + if not pattern: + pattern =3D caller_file + + loader =3D unittest.TestLoader() + suite =3D loader.discover(start_dir=3Dos.path.dirname(caller_f= ile), + pattern=3Dos.path.basename(caller_file= )) + + # Flatten the suite for environment injection + tests_to_inject =3D flatten_suite(suite) + + # Filter tests by method name if -k specified + if args.keyword: + try: + pattern =3D re.compile(args.keyword) + filtered_suite =3D unittest.TestSuite() + for test in tests_to_inject: # Use the pre-flattened list + method_name =3D test.id().split(".")[-1] + if pattern.search(method_name): + filtered_suite.addTest(test) + suite =3D filtered_suite + except re.error as e: + sys.stderr.write(f"Invalid regex pattern: {e}\n") + sys.exit(1) + else: + # Maintain original suite structure if no keyword filtering + suite =3D unittest.TestSuite(tests_to_inject) + + if verbose >=3D 2: + resultclass =3D None + else: + resultclass =3D Summary + + runner =3D unittest.TextTestRunner(verbosity=3Dargs.verbose, + resultclass=3Dresultclass, + failfast=3Dargs.failfast) + result =3D runner.run(suite) + if resultclass: + result.printResults() + + sys.exit(not result.wasSuccessful()) + + +def run_unittest(fname): + """ + Basic usage of TestUnits class. + + Use it when there's no need to pass any extra argument to the tests + with. The recommended way is to place this at the end of each + unittest module:: + + if __name__ =3D=3D "__main__": + run_unittest(__file__) + """ + TestUnits().run(fname) --=20 2.52.0 From nobody Sat Feb 7 17:55:25 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 B695235B63A; Sat, 31 Jan 2026 14:25: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=1769869522; cv=none; b=fK1Lbj4HDcFTK7a7voYRhbpRAOaN9RJ0/CLXp1xfiRl2h6mMmHw3BL3/T6QXoqGyEK5NqXYmv3BWzNKZAq5auHb+IRii57fSoJpjB0mbe4V/PuMwfv79crWcQ1yhnVO9UQ5pgsvJsSUvuZQVvzix/h/HKkrQjhyO4Hd8DWXupT0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769869522; c=relaxed/simple; bh=BBoYIDvTc4/ZRDpBii5k/vxa0438Gqzt0Fqrx3bypIQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Xza512brSLqsjg5/LQxJ8f7nSmh+BIZwhMduIAfbaisC/l7F/2o53vbdSTyvnMGHz25jbu/21u/apS4hDnUpA35RvrmCZg8B+dR5nby/3kuCDEJN6Sg7CBNL3525kOf6D+Q63toeTstSySom3wcS/ZlAenbZXLPUmoxpV+W4DuY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=XfC7C9GX; 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="XfC7C9GX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 30946C4DDF2; Sat, 31 Jan 2026 14:25:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769869522; bh=BBoYIDvTc4/ZRDpBii5k/vxa0438Gqzt0Fqrx3bypIQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XfC7C9GXjgcC3bK4pVfL/M0YbnVLJf+h24CzHZ+giiSpzH2BFGgGNQ7fN0n9/u7Kh UNoQaJyEU2t3gOyoRFq44/qIo8NG8NotEPNT+ppK8CziERcCMZysBJcoV005dAfAL+ ilBtg8RTllg9DrkKWwS1JoolakTPwaIFkb3WgBcz5wFddBg3CkjcBEjcR+O98j5yV8 fsn0kKD9t7sLEnixqLDxR73oa2IDmTYJ21FlLPt6miJQV4KjwsEf9EjoLFzlHpKB9E l1/lY8P2qf5/lStvrdThacFtFSEARL94VaaAWfsbnaeP0eBAxs7xGU6eRFrKgCDjPS +mGijVX0jySPA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vmBua-0000000AVmR-1p2Y; Sat, 31 Jan 2026 15:25:20 +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" , Mauro Carvalho Chehab , Randy Dunlap Subject: [PATCH v4 41/41] tools: unittests: add tests for kernel-doc NestedMatch and KernRe Date: Sat, 31 Jan 2026 15:25:15 +0100 Message-ID: <5132658a4c47babf905f1e469eba289ae1ebdc8c.1769867954.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The NestedMatch logic is complex enough to justify tests to ensure that it is doing its job. Add unittests to check the functionality provided by NestedMatch by replicating expected patterns. The NestedMatch class handles with complex macros. Add an unittest to check if its doing the right thing and detect eventual regressions as we improve its code. The initial version was generated using gpt-oss:latest LLM on my local GPU, as LLMs aren't bad transforming patterns into unittests. Yet, the curent version contains only the skeleton of what LLM produced, as I ended higly changing its content to be more representative and to have real case scenarios. The kdoc_xforms test suite contains 3 test groups. Two of them tests the basic functionality of NestedMatch to replace patterns. The last one (TestRealUsecases) contains real code snippets from the Kernel with some cleanups to better fit in 80 columns and uses the same transforms as kernel-doc, thus allowing to test the logic used inside kdoc_parser to transform functions, structs and variable patterns. Its output is like this: $ tools/unittests/kdoc_xforms.py Ran 25 tests in 0.003s OK kdoc_xforms: TestDifferentReplacements: test_strip_multiple_acquires: OK test_sub_count_parameter: OK test_sub_mixed_placeholders: OK test_sub_multiple_placeholders: OK test_sub_no_placeholder: OK test_sub_single_placeholder: OK test_sub_with_capture: OK test_sub_zero_placeholder: OK TestMultipleMacros: test_acquires_multiple: OK test_acquires_nested_paren: OK test_acquires_simple: OK test_mixed_macros: OK test_must_hold: OK test_must_hold_shared: OK test_no_false_positive: OK test_no_function: OK test_no_macro_remains: OK TestRealUsecases: test_functions_with_acquires_and_releases: OK test_raw_struct_group: OK test_raw_struct_group_tagged: OK test_struct_group: OK test_struct_group_attr: OK test_struct_group_tagged_with_private: OK test_struct_kcov: OK test_vars_stackdepot: OK Ran 25 tests Signed-off-by: Mauro Carvalho Chehab --- tools/unittests/kdoc_xforms.py | 654 +++++++++++++++++++++++++++++++++ 1 file changed, 654 insertions(+) create mode 100755 tools/unittests/kdoc_xforms.py diff --git a/tools/unittests/kdoc_xforms.py b/tools/unittests/kdoc_xforms.py new file mode 100755 index 000000000000..71b42c8c75ea --- /dev/null +++ b/tools/unittests/kdoc_xforms.py @@ -0,0 +1,654 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright(c) 2026: Mauro Carvalho Chehab . +# +# pylint: disable=3DC0413,R0904 + + +""" +Unit tests for kernel-doc NestedMatch. +""" + +import os +import re +import sys +import unittest + + +# Import Python modules + +SRC_DIR =3D os.path.dirname(os.path.realpath(__file__)) +sys.path.insert(0, os.path.join(SRC_DIR, "../lib/python")) + +from kdoc.kdoc_re import NestedMatch, CFunction +from kdoc.xforms_lists import CTransforms +from unittest_helper import run_unittest + +# +# Override unittest.TestCase to better compare diffs ignoring whitespaces +# +class TestCaseDiff(unittest.TestCase): + """ + Disable maximum limit on diffs and add a method to better + handle diffs with whitespace differences. + """ + + @classmethod + def setUpClass(cls): + """Ensure that there won't be limit for diffs""" + cls.maxDiff =3D None + + def assertLogicallyEqual(self, a, b): + """ + Compare two results ignoring multiple whitespace differences. + + This is useful to check more complex matches picked from examples. + On a plus side, we also don't need to use dedent. + Please notice that line breaks still need to match. We might + remove it at the regex, but this way, checking the diff is easier. + """ + a =3D re.sub(r"[\t ]+", " ", a.strip()) + b =3D re.sub(r"[\t ]+", " ", b.strip()) + + a =3D re.sub(" ;", ";", a) + b =3D re.sub(" ;", ";", b) + + self.assertEqual(a, b) + +# +# Tests doing with different macros +# + +class TestMultipleMacros(TestCaseDiff): + """ + Tests doing with different macros. + + Here, we won't use assertLogicallyEqual. Instead, we'll check if each + of the expected patterns are present at the answer. + """ + + def test_acquires_simple(self): + """Simple replacement test with __acquires""" + line =3D "__acquires(ctx) foo();" + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + + self.assertNotIn("__acquires(", result) + self.assertIn("foo();", result) + + def test_acquires_multiple(self): + """Multiple __acquires""" + line =3D "__acquires(ctx) __acquires(other) bar();" + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + + self.assertNotIn("__acquires(", result) + self.assertEqual(result.count("REPLACED"), 2) + + def test_acquires_nested_paren(self): + """__acquires with nested pattern""" + line =3D "__acquires((ctx1, ctx2)) baz();" + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + + self.assertNotIn("__acquires(", result) + self.assertIn("baz();", result) + + def test_must_hold(self): + """__must_hold with a pointer""" + line =3D "__must_hold(&lock) do_something();" + result =3D NestedMatch(r"__must_hold\s*\(").sub("REPLACED", line) + + self.assertNotIn("__must_hold(", result) + self.assertIn("do_something();", result) + + def test_must_hold_shared(self): + """__must_hold with an upercase defined value""" + line =3D "__must_hold_shared(RCU) other();" + result =3D NestedMatch(r"__must_hold_shared\s*\(").sub("REPLACED",= line) + + self.assertNotIn("__must_hold_shared(", result) + self.assertIn("other();", result) + + def test_no_false_positive(self): + """ + Ensure that unrelated text containing similar patterns is preserved + """ + line =3D "call__acquires(foo); // should stay intact" + result =3D NestedMatch(r"\b__acquires\s*\(").sub("REPLACED", line) + + self.assertEqual(result, line) + + def test_mixed_macros(self): + """Add a mix of macros""" + line =3D "__acquires(ctx) __releases(ctx) __must_hold(&lock) foo()= ;" + + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + result =3D NestedMatch(r"__releases\s*\(").sub("REPLACED", result) + result =3D NestedMatch(r"__must_hold\s*\(").sub("REPLACED", result) + + self.assertNotIn("__acquires(", result) + self.assertNotIn("__releases(", result) + self.assertNotIn("__must_hold(", result) + + self.assertIn("foo();", result) + + def test_no_macro_remains(self): + """Ensures that unmatched macros are untouched""" + line =3D "do_something_else();" + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + + self.assertEqual(result, line) + + def test_no_function(self): + """Ensures that no functions will remain untouched""" + line =3D "something" + result =3D NestedMatch(line).sub("REPLACED", line) + + self.assertEqual(result, line) + +# +# Check if the diff is logically equivalent. To simplify, the tests here +# use a single macro name for all replacements. +# + +class TestDifferentReplacements(TestCaseDiff): + """ + Test argument replacements. + + Here, the function name can be anything. So, we picked __attribute__(), + to mimic a macro found at the Kernel, but none of the replacements her + has any relationship with the Kernel usage. + """ + + MACRO =3D "__attribute__" + + @classmethod + def setUpClass(cls): + """Define a NestedMatch to be used for all tests""" + cls.matcher =3D NestedMatch(re.compile(rf"{cls.MACRO}\s*\(")) + + def test_sub_with_capture(self): + """Test all arguments replacement with a single arg""" + line =3D f"{self.MACRO}(&ctx)\nfoo();" + + result =3D self.matcher.sub(r"ACQUIRED(\0)", line) + + self.assertLogicallyEqual("ACQUIRED(&ctx)\nfoo();", result) + + def test_sub_zero_placeholder(self): + """Test all arguments replacement with a multiple args""" + line =3D f"{self.MACRO}(arg1, arg2)\nbar();" + + result =3D self.matcher.sub(r"REPLACED(\0)", line) + + self.assertLogicallyEqual("REPLACED(arg1, arg2)\nbar();", result) + + def test_sub_single_placeholder(self): + """Single replacement rule for \1""" + line =3D f"{self.MACRO}(ctx, boo)\nfoo();" + result =3D self.matcher.sub(r"ACQUIRED(\1)", line) + + self.assertLogicallyEqual("ACQUIRED(ctx)\nfoo();", result) + + def test_sub_multiple_placeholders(self): + """Replacement rule for both \1 and \2""" + line =3D f"{self.MACRO}(arg1, arg2)\nbar();" + result =3D self.matcher.sub(r"REPLACE(\1, \2)", line) + + self.assertLogicallyEqual("REPLACE(arg1, arg2)\nbar();", result) + + def test_sub_mixed_placeholders(self): + """Replacement rule for \0, \1 and additional text""" + line =3D f"{self.MACRO}(foo, bar)\nbaz();" + result =3D self.matcher.sub(r"ALL(\0) FIRST(\1)", line) + + self.assertLogicallyEqual("ALL(foo, bar) FIRST(foo)\nbaz();", resu= lt) + + def test_sub_no_placeholder(self): + """Replacement without placeholders""" + line =3D f"{self.MACRO}(arg)\nfoo();" + result =3D self.matcher.sub(r"NO_BACKREFS()", line) + + self.assertLogicallyEqual("NO_BACKREFS()\nfoo();", result) + + def test_sub_count_parameter(self): + """Verify that the algorithm stops after the requested count""" + line =3D f"{self.MACRO}(a1) x();\n{self.MACRO}(a2) y();" + result =3D self.matcher.sub(r"ONLY_FIRST(\1) ", line, count=3D1) + + self.assertLogicallyEqual(f"ONLY_FIRST(a1) x();\n{self.MACRO}(a2) = y();", + result) + + def test_strip_multiple_acquires(self): + """Check if spaces between removed delimiters will be dropped""" + line =3D f"int {self.MACRO}(1) {self.MACRO}(2 ) {self.MACRO}(3)= foo;" + result =3D self.matcher.sub(r"", line) + + self.assertLogicallyEqual(result, "int foo;") + + +# +# Test struct_group replacements +# + + +class TestRealUsecases(TestCaseDiff): + """ + Test diferent usecase patterns found at the Kernel. + + Here, replacements using both NestedMatch and KernRe can be tested, + as it will import the actual replacement rules used by kernel-doc. + """ + + xforms =3D { + "func": CTransforms.function_xforms, + "struct": CTransforms.struct_xforms, + "var": CTransforms.var_xforms, + } + + @classmethod + def apply_transforms(cls, xform_type, text): + """ + Mimic the behavior of kdoc_parser.apply_transforms() method. + + For each element of STRUCT_XFORMS, apply apply_transforms. + + There are two parameters: + + - ``xform_type`` + Can be ``func``, ``struct`` or ``var``; + - ``text`` + The text where the sub patterns from CTransforms will be appli= ed. + """ + for search, subst in cls.xforms.get(xform_type): + text =3D search.sub(subst, text) + + return text.strip() + + cls.matcher =3D NestedMatch(r"\bstruct_group[\w\_]*\(") + + def test_struct_group(self): + """ + Test struct_group using a pattern from + drivers/net/ethernet/asix/ax88796c_main.h. + """ + line =3D """ + struct tx_pkt_info { + struct_group(tx_overhead, + struct tx_sop_header sop; + struct tx_segment_header seg; + ); + struct tx_eop_header eop; + u16 pkt_len; + u16 seq_num; + }; + """ + expected =3D """ + struct tx_pkt_info { + struct tx_sop_header sop; + struct tx_segment_header seg;; + struct tx_eop_header eop; + u16 pkt_len; + u16 seq_num; + }; + """ + + result =3D self.apply_transforms("struct", line) + self.assertLogicallyEqual(result, expected) + + def test_struct_group_attr(self): + """ + Test two struct_group_attr using patterns from fs/smb/client/cifsp= du.h. + """ + line =3D """ + typedef struct smb_com_open_rsp { + struct smb_hdr hdr; /* wct =3D 34 BB */ + __u8 AndXCommand; + __u8 AndXReserved; + __le16 AndXOffset; + __u8 OplockLevel; + __u16 Fid; + __le32 CreateAction; + struct_group_attr(common_attributes, __packed, + __le64 CreationTime; + __le64 LastAccessTime; + __le64 LastWriteTime; + __le64 ChangeTime; + __le32 FileAttributes; + ); + __le64 AllocationSize; + __le64 EndOfFile; + __le16 FileType; + __le16 DeviceState; + __u8 DirectoryFlag; + __u16 ByteCount; /* bct =3D 0 */ + } __packed OPEN_RSP; + + typedef struct { + struct_group_attr(common_attributes, __packed, + __le64 CreationTime; + __le64 LastAccessTime; + __le64 LastWriteTime; + __le64 ChangeTime; + __le32 Attributes; + ); + __u32 Pad1; + __le64 AllocationSize; + __le64 EndOfFile; + __le32 NumberOfLinks; + __u8 DeletePending; + __u8 Directory; + __u16 Pad2; + __le32 EASize; + __le32 FileNameLength; + union { + char __pad; + DECLARE_FLEX_ARRAY(char, FileName); + }; + } __packed FILE_ALL_INFO; /* level 0x107 QPathInfo */ + """ + expected =3D """ + typedef struct smb_com_open_rsp { + struct smb_hdr hdr; /* wct =3D 34 BB */ + __u8 AndXCommand; + __u8 AndXReserved; + __le16 AndXOffset; + __u8 OplockLevel; + __u16 Fid; + __le32 CreateAction; + __le64 CreationTime; + __le64 LastAccessTime; + __le64 LastWriteTime; + __le64 ChangeTime; + __le32 FileAttributes;; + __le64 AllocationSize; + __le64 EndOfFile; + __le16 FileType; + __le16 DeviceState; + __u8 DirectoryFlag; + __u16 ByteCount; /* bct =3D 0 */ + } OPEN_RSP; + + typedef struct { + __le64 CreationTime; + __le64 LastAccessTime; + __le64 LastWriteTime; + __le64 ChangeTime; + __le32 Attributes;; + __u32 Pad1; + __le64 AllocationSize; + __le64 EndOfFile; + __le32 NumberOfLinks; + __u8 DeletePending; + __u8 Directory; + __u16 Pad2; + __le32 EASize; + __le32 FileNameLength; + union { + char __pad; + char FileName[]; + }; + } FILE_ALL_INFO; /* level 0x107 QPathInfo */ + """ + + result =3D self.apply_transforms("struct", line) + self.assertLogicallyEqual(result, expected) + + def test_raw_struct_group(self): + """ + Test a __struct_group pattern from include/uapi/cxl/features.h. + """ + line =3D """ + struct cxl_mbox_get_sup_feats_out { + __struct_group(cxl_mbox_get_sup_feats_out_hdr, hdr, /* emp= ty */, + __le16 num_entries; + __le16 supported_feats; + __u8 reserved[4]; + ); + struct cxl_feat_entry ents[] __counted_by_le(num_entries); + } __attribute__ ((__packed__)); + """ + expected =3D """ + struct cxl_mbox_get_sup_feats_out { + __le16 num_entries; + __le16 supported_feats; + __u8 reserved[4];; + struct cxl_feat_entry ents[]; + }; + """ + + result =3D self.apply_transforms("struct", line) + self.assertLogicallyEqual(result, expected) + + def test_raw_struct_group_tagged(self): + """ + Test some struct_group_tagged patterns from drivers/cxl/cxl.h. + """ + line =3D """ + struct cxl_regs { + struct_group_tagged(cxl_component_regs, component, + void __iomem *hdm_decoder; + void __iomem *ras; + ); + + struct_group_tagged(cxl_device_regs, device_regs, + void __iomem *status, *mbox, *memdev; + ); + + struct_group_tagged(cxl_pmu_regs, pmu_regs, + void __iomem *pmu; + ); + + struct_group_tagged(cxl_rch_regs, rch_regs, + void __iomem *dport_aer; + ); + + struct_group_tagged(cxl_rcd_regs, rcd_regs, + void __iomem *rcd_pcie_cap; + ); + }; + """ + expected =3D """ + struct cxl_regs { + struct cxl_component_regs component; void __iomem *hdm_decoder; + void __iomem *ras;; + + struct cxl_device_regs device_regs; void __iomem *status; + + struct cxl_pmu_regs pmu_regs; void __iomem *pmu;; + + struct cxl_rch_regs rch_regs; void __iomem *dport_aer;; + + struct cxl_rcd_regs rcd_regs; void __iomem *rcd_pcie_cap;; + }; + """ + + result =3D self.apply_transforms("struct", line) + self.assertLogicallyEqual(result, expected) + + def test_struct_group_tagged_with_private(self): + """ + Replace struct_group_tagged with private, using the same regex + for the replacement as what happens in xforms_lists.py. + + As the private removal happens outside NestedGroup class, we manua= lly + dropped the remaining part of the struct, to simulate what happens + at kdoc_parser. + + Taken from include/net/page_pool/types.h + """ + line =3D """ + 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 */ + """ + expected =3D """ + struct page_pool_params { + struct 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 page_pool_params_slow slow; struct net_device *netd= ev; + unsigned int queue_idx; + unsigned int flags; + /* private: used by test code only */ + """ + + result =3D self.apply_transforms("struct", line) + self.assertLogicallyEqual(result, expected) + + def test_struct_kcov(self): + """ + """ + line =3D """ + struct kcov { + refcount_t refcount; + spinlock_t lock; + enum kcov_mode mode __guarded_by(&lock); + unsigned int size __guarded_by(&lock); + void *area __guarded_by(&lock); + struct task_struct *t __guarded_by(&lock); + bool remote; + unsigned int remote_size; + int sequence; + }; + """ + expected =3D """ + """ + + result =3D self.apply_transforms("struct", line) + self.assertLogicallyEqual(result, expected) + + + def test_struct_kcov(self): + """ + Test a struct from kernel/kcov.c. + """ + line =3D """ + struct kcov { + refcount_t refcount; + spinlock_t lock; + enum kcov_mode mode __guarded_by(&lock); + unsigned int size __guarded_by(&lock); + void *area __guarded_by(&lock); + struct task_struct *t __guarded_by(&lock); + bool remote; + unsigned int remote_size; + int sequence; + }; + """ + expected =3D """ + struct kcov { + refcount_t refcount; + spinlock_t lock; + enum kcov_mode mode; + unsigned int size; + void *area; + struct task_struct *t; + bool remote; + unsigned int remote_size; + int sequence; + }; + """ + + result =3D self.apply_transforms("struct", line) + self.assertLogicallyEqual(result, expected) + + def test_vars_stackdepot(self): + """ + Test guarded_by on vars from lib/stackdepot.c. + """ + line =3D """ + size_t pool_offset __guarded_by(&pool_lock) =3D DEPOT_POOL_SIZ= E; + __guarded_by(&pool_lock) LIST_HEAD(free_stacks); + void **stack_pools __pt_guarded_by(&pool_lock); + """ + expected =3D """ + size_t pool_offset =3D DEPOT_POOL_SIZE; + struct list_head free_stacks; + void **stack_pools; + """ + + result =3D self.apply_transforms("var", line) + self.assertLogicallyEqual(result, expected) + + def test_functions_with_acquires_and_releases(self): + """ + Test guarded_by on vars from lib/stackdepot.c. + """ + line =3D """ + bool prepare_report_consumer(unsigned long *flags, + const struct access_info *ai, + struct other_info *other_info) \ + __cond_acquires(true, &report_lock= ); + + int tcp_sigpool_start(unsigned int id, struct tcp_sigpool *c) \ + __cond_acquires(0, RCU_BH); + + bool undo_report_consumer(unsigned long *flags, + const struct access_info *ai, + struct other_info *other_info) \ + __cond_releases(true, &report_lock); + + void debugfs_enter_cancellation(struct file *file, + struct debugfs_cancellation *c= ) \ + __acquires(cancellation); + + void debugfs_leave_cancellation(struct file *file, + struct debugfs_cancellation *c= ) \ + __releases(cancellation); + + acpi_cpu_flags acpi_os_acquire_lock(acpi_spinlock lockp) \ + __acquires(lockp); + + void acpi_os_release_lock(acpi_spinlock lockp, + acpi_cpu_flags not_used) \ + __releases(lockp) + """ + expected =3D """ + bool prepare_report_consumer(unsigned long *flags, + const struct access_info *ai, + struct other_info *other_info); + + int tcp_sigpool_start(unsigned int id, struct tcp_sigpool *c); + + bool undo_report_consumer(unsigned long *flags, + const struct access_info *ai, + struct other_info *other_info); + + void debugfs_enter_cancellation(struct file *file, + struct debugfs_cancellation *c= ); + + void debugfs_leave_cancellation(struct file *file, + struct debugfs_cancellation *c= ); + + acpi_cpu_flags acpi_os_acquire_lock(acpi_spinlock lockp); + + void acpi_os_release_lock(acpi_spinlock lockp, + acpi_cpu_flags not_used) + """ + + result =3D self.apply_transforms("func", line) + self.assertLogicallyEqual(result, expected) + + +# +# Run all tests +# +if __name__ =3D=3D "__main__": + run_unittest(__file__) --=20 2.52.0