From nobody Wed Feb 11 02:24:22 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 C0FDE30C60D; Wed, 28 Jan 2026 16:50:31 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619031; cv=none; b=gcv593hYuuBEMbdwn3EDkruSd6e1eBjw2XzYkPjZnN0LC/7uHhKBSXUioNMqjxXISdCo8u5CwxtHAA4pqlo0GgFztgI2L9T1fLAXTApraO/C/EP8M1MZ7v7LoDxYTpGZs/WIncsuElYJujqEndU5uzmIM1pwM8RGTjW18sT7xTQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619031; c=relaxed/simple; bh=Mtp3U2b4BAZhIQ5Am742/0g+jFDD4JwsLEBjzPmmPH0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=S9m4AF/fryQdEb1njxsDV9LH/O+SP6sn+S4yMhx4YJy7MUT+fibaJmvLqQ89EKo1k5655HEcXHG8FBAIGXE2d+RKTf/Fy4JS3wWeJeGMaL6VL8Er6uyBVyWMSyr/XUjaf/uA7cmJpFFNUYJwca0MfSIkxSlJRPndo9cNwAZTjeo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=nmixZLGV; 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="nmixZLGV" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 753C3C4CEF1; Wed, 28 Jan 2026 16:50:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619031; bh=Mtp3U2b4BAZhIQ5Am742/0g+jFDD4JwsLEBjzPmmPH0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nmixZLGVxxndMEUPOHEcC/ljHC7OcOHdhG+qCVStSGMa2pJuMpU+5U6vYAA0Rado9 7/BBAD1SmTMSLtmcV2BWclNTvWNUGWklzQ+UvMzyNMdZ9pI6VgTyAgNAROUzJVnmGf fnAntSedfmRPvM70thFn/o1Rsv12zu2a6NycKT3pzy+85fMrF4AycL0Sd5Zblrya5o x9X6XiVPTKxFhU8iwjiaAO3pTF6l4HuHpP1Wd9q6SpH1wXr2zB37UAhGG7YUaeyspf 2CHq5z8GI+DBlIT2SmgLxmUotLFzm1ZlykGEa+dJLoETKe0HGJ0pj1/Gabbn4uJbB+ 7258GfjWTox0g== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kO-0000000DAkj-3zTj; Wed, 28 Jan 2026 17:50:28 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 01/25] docs: kdoc_re: add support for groups() Date: Wed, 28 Jan 2026 17:49:59 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab 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 Wed Feb 11 02:24:22 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 A398E308F1D; Wed, 28 Jan 2026 16:50:31 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619031; cv=none; b=GUIoIktBOJn0e7CRwGJ7c8CwHbtYxm7E99RbGd+fYNx1EK0TN0a7VceNXTx2Zknv7IgSx+CtLW9iyEE+YKKsYQJJJkUOn3LT7CkLR8Zed3krdUwfmA7fHRVLBsFxEF0g/3eVpsZFjaZulLTDZuFG7CSa9y5hXuTdxHgGJC9xvc8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619031; c=relaxed/simple; bh=aGtXVSLt63dj+krdfmEJciMSaeT6Bvc5GNuMaIsTXoE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=iFj1mPyPpFEwOMo/P1JMqeedtgDM9YXHxbDJso2h33/LeGjYSWKMyyarGQrTLOIJ4j4cpIJrzLzPt+ukxZtB/4+G+RnLHeMVtrlTskiY8T7PR3KwggBIrSLcTTL7NOR7aMT0TEH9RfcNk7nUG3M6WW1/Db/1iA1YSJC78XIUCaQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=YRDmxRMZ; 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="YRDmxRMZ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 82133C116C6; Wed, 28 Jan 2026 16:50:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619031; bh=aGtXVSLt63dj+krdfmEJciMSaeT6Bvc5GNuMaIsTXoE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YRDmxRMZ0TzXKcpO7QPAVwYDCDc3JRzXCi/2vphb6QF2Welq2DuKlFB52U++EO8hL K/40ydkrdzvpiAs0fqddXMZBPj3aj18lb+m7tBinObVxGJaqrc42AatBYVJ6ji5MSA YEpTNsBwsHAzeYrIY99+LitgQ8/LQnOfJVhwonUg84ZmdD5kcUlseiNbHpQvX1LRMl +72Y4kOMUjOvY2INLp/+QZwhB5ZcpTNtSZPPTIqMNOB1bjS1RIWFDqavuxyj68jxxg rvW+STocPvu27AVf7kQPsDsnV0IepbwsNmkWiULIfhfTw4QevaOKTrrAB07Hs4fme9 VX6y4qXJ1/qFA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kP-0000000DAlv-17Vl; Wed, 28 Jan 2026 17:50:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 02/25] docs: kdoc_re: don't go past the end of a line Date: Wed, 28 Jan 2026 17:50:00 +0100 Message-ID: <1784349130a32df07aca486eb88711dd5d21c3b2.1769617841.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The logic which checks if the line ends with ";" is currently broken: it may try to read past the buffer. Fix it by checking before trying to access line[pos]. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 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 Wed Feb 11 02:24:22 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 C0F6030BF4F; Wed, 28 Jan 2026 16:50:31 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619031; cv=none; b=IVI42wVNz9uq89QSE/oB9WqKJ3F+4zMPjNkiKZtJ7ZX1ABaotZ+E1EUBB3qCDT1zzwB3MZMmA1pGf1mPGioBTFws7XIHbzBbiGJLn4C9/fuec/8TxYAaX5vFx8ESfeIXERg8qirwBvxNgXcCE7mXLGcb6qx+zdo0o6Y3r7Dg0V4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619031; c=relaxed/simple; bh=1OHigLaB0I9Gr4pd6M4Zc3FWOaEqquAXFRRO/Gxw3CM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=NOMki0x03rCpl/PMz7iaMApdLBt5k5N6uCu8Wncl02TO5Uw0iuiAArGfynuERVWBBJVNMzg+XGs3SwIhclhSMggbN/0rA8rDxXWveK/s56bZraGVAL+0iNT2reY/CYvoBD49uoJNlXRyVOyE0xNGhKKVRYi0hJ3r9MYo4KOUIGI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=TjfXEptm; 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="TjfXEptm" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8AA2BC2BC86; Wed, 28 Jan 2026 16:50:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619031; bh=1OHigLaB0I9Gr4pd6M4Zc3FWOaEqquAXFRRO/Gxw3CM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=TjfXEptm0ADY3ifgqaYHKezKdvmZ0vdiu4HJLMBS7TERWWChwTE1Xzyeiuawdcaau 7989W1/+LpY6k5kTjByO0/pedG+2Fau/rP7VQrEFfnNa21MOP98mp6x+tpR/0t8g1F ZZUyM2fgjTeBFBBGeu53u1D/WrM7HHTeTKuNF32yRhacr0ydl40FC6ViV+OKZfx9Cp cVe49eQdgNKHSOAJr+sb8eo5n6T5Le49xwuw8FTQrCTdAbEUDlwa9IwlwPQZLTaOdC zEw58RSxgeWu+Nrfi6iiYe0ALr0VH7//l/jWCLXmAZRGQXl/rrV9BkB0gorneZ3QFh fMboor8w+ReGw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kP-0000000DAn7-2H9M; Wed, 28 Jan 2026 17:50:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 03/25] docs: kdoc_parser: move var transformers to the beginning Date: Wed, 28 Jan 2026 17:50:01 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab 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 Wed Feb 11 02:24:22 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 D44E63148D3; Wed, 28 Jan 2026 16:50:31 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619031; cv=none; b=qe6u+w7srHHDC2dpS+w1aora37csYdCDqjEgE7sML2hACmOiu43gxS8qBrMJUt7oXRikItMrFMKWCHsXRZ53LSHPU0oAzY+w5wi+E1IkqGZ7jgAzyoaT2BthcaS/CV+7hGfmLgZa3Z27LZSYEsD+ELApcY47ltTFonEMUc6yi7I= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619031; c=relaxed/simple; bh=cuKy1d1D0xiQwJcdcAdfKB7F5IpylCi/Hc8WUScKfcE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=UWMyGF2D5ubPXuE7wqtF/Bcjvs+JkbITTZ2jc9LQKu76OdsKo6x1EMQnFzmFWwOcLJ47+CI0YRU4Aypc1APxjDKtKm7DXVujRrYXBkf9aP4zJJwELdC3UyuRHOlrBxVDaUcImB1zAvMzYQIxB2hIDjRbqVsb5vPbuurfFNgpO0E= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=LnuH8udN; 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="LnuH8udN" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B29A8C16AAE; Wed, 28 Jan 2026 16:50:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619031; bh=cuKy1d1D0xiQwJcdcAdfKB7F5IpylCi/Hc8WUScKfcE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=LnuH8udNWV3JcvZ1e6laVHL0sFlIGbyZ6iWd8jYwZx6/7G4qJNtaF80Y+Cp87/bdz vk/e0AZUIXJlTyQGjj64algtpG8eAfAf1MjNDTMD5xQOn0DLCQaaA/z6+jMCWbYphs whcNXpuGtleC01nJ45Oy9wPKrBCEaVzthZ6cZQtf1Mmv+f2XMrJHV354VHBgPbgZDY Ej4CGDN9f+KS6fzg0oS+W1BnE3kyD9Zm3WLLB36rYHbN/wPaOn62m8kmC9bhslgK76 0DzEOEH8xViMIgyHE1GwXif3L5CcCoNjY4+sYFfLUBuDWPj9fM1ThFpJEDuVEy1Dlh yvV6j99dJ5QGQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kP-0000000DAoJ-3ZM3; Wed, 28 Jan 2026 17:50:29 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 04/25] docs: kdoc_parser: don't mangle with function defines Date: Wed, 28 Jan 2026 17:50:02 +0100 Message-ID: <05cf7e030b659f26ebc4fdc65e264ea9616c9d9d.1769617841.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 Wed Feb 11 02:24:22 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 86FD22DECDF; Wed, 28 Jan 2026 16:50:32 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619032; cv=none; b=oKTRdMcihEqT3AKSgBWkjoUnxdmG/du5J50MQtLRsxav1u1U+mbt1W1NUUx9NG8f1Vy1RMLQl9c1oqYZXfrknjhmDbeYTRpYthgbW/86IdnXgSVG79JWi/bVoZZIR2uz9tk0+Pl9hVlfigcj8WeLjcXS75UKKvBhH/06aE8uQaw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619032; c=relaxed/simple; bh=1UyEpa3PQCXAaiGwapZKBeWnBxx40S80+WhX3uQJt4s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=XJRpokZSjemknL5aYB3lHGhCBelsbKyeps7CrwaKQemCgAvG5F5bp+EYf8KgjUQLijj5dg8YbxS2vEO3icRFhmT/S+IQ1sEIZnVKmIjOqju1Ky1Ght5koZLWCsYmX566n7kuloSd9PPMfJZ05O+e38WKt53VyU2nPRV3myDIUqs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=KXBvlD1Y; 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="KXBvlD1Y" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 62FC9C4CEF1; Wed, 28 Jan 2026 16:50:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619032; bh=1UyEpa3PQCXAaiGwapZKBeWnBxx40S80+WhX3uQJt4s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KXBvlD1YlPUkuhCdRNoOlAMLVwBTw2cEK/blQt2z+tT6+6xhg/bb/acS8rd7SM5Qt XBqvwMDb/YXDBAn/cuwuy5rjpHfmBF3YVCKWiKRE7mSussyKmfWaRlkngZSYZNXwJL Scrgtfdb1ppIWwWXuBShOIh5H3y5CQ9k7vJSEM9FsltuL2STrp4Mt7MxHTco1JsqYh cStQhhCFszwUTKZkTUVUfsB24IxOhEQQ8WVcuauqr0++QiLuSCOr0DNhdbTOSlJDRL FScuHqnceVeZ0E/N++vKAczeV9305tVX7xsDoV59JcxzFAbwMssB+sMXahhne29zKR mTBODpcVzijsw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kQ-0000000DApU-0X8N; Wed, 28 Jan 2026 17:50:30 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 05/25] docs: kdoc_parser: add functions support for NestedMatch Date: Wed, 28 Jan 2026 17:50:03 +0100 Message-ID: <43b1fb838ba73c3efc18ab605b892f531ffbed01.1769617841.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. 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 --- 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 Wed Feb 11 02:24:22 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 9EB9132D7FB; Wed, 28 Jan 2026 16:50:32 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619032; cv=none; b=tHzuL5tF+qHwc8wZ0X78wmza2z8xdMUsrTS5oyjeE4QM6qY8yCunET7BGUMmPc6IUdoy45TwV/7J5GeHIH+NufaLSP4RNBvPkjU8WliV6/rVdRX0y4x0CR4LfhCKotcpJr4gy8LWQktoMMMw9gA/8Ig+PRBqNFGBi3rpxCxzWtU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619032; c=relaxed/simple; bh=Rc+cvBbCrvl5gHPyjY0jltfZsAtkaYF+V2rrj3nvojw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=kPD7cXCZEegThUUFDFsD2BPUMf6FJ/n9UvISzBvF6OibQhIxvMrlMpLwbX4yTgB3F8uPCP0FgSWYjCDaVVHlL8gmoAv3Eir3WAhv64wzVYWdtRyNDIVtxAR5KZAyanhcKidQWWI0jgd3pl0380VDKjLXsNO5XBOpvb9hHP4y8DI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=cScZw03Y; 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="cScZw03Y" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 69DBFC116C6; Wed, 28 Jan 2026 16:50:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619032; bh=Rc+cvBbCrvl5gHPyjY0jltfZsAtkaYF+V2rrj3nvojw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=cScZw03YddUXVcztOtXAVx42vO/hlulf7PHru1VjgHAhVSmXdImxkmdeBTi9dIaXo rbRTQtEPWPLtq5o3abyVEDEeEY6C0H11KpiC9lRC6aNem/KzxY9KM8rbE9ZY81TyIb Db0P/2CSRJYIxc1uuFYpTmsy8fQu3ync9SAaqplq1K/rBwS6KaPcHLi/znGZyK80kC lHUu9B+td2Sd/DmCn0MF1AMkXRZ33yzh3rH9COWRtpOUrouLNnQK05tK5pAh9gksJv Y5jSylUilJ1ykhQEt6DTrsnT1SbHR1at4RaLTEBDNCrnafbzBwALUf/4q2ja9CyneK 3ks4m1cN6PR2w== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kQ-0000000DAqf-1hgM; Wed, 28 Jan 2026 17:50:30 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 06/25] docs: kdoc_parser: use NestedMatch to handle __attribute__ on functions Date: Wed, 28 Jan 2026 17:50:04 +0100 Message-ID: <9c77e55b771dc19f0c1203bc107f69c8c2c371c5.1769617841.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 --- 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 Wed Feb 11 02:24:22 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 8706732C306; Wed, 28 Jan 2026 16:50:32 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619032; cv=none; b=cvD4yB8iuCikA2MqyOT/ZzmnRV01+9rYkYBWIwvoUAU5ib56XPzIogJYJ/9Zacj7WVZv5KFL9NURgW9I6Wj+xD6EkH8hBpFUzMBhruMWvxs/2c8rJ+KC13L1VGgzMFMOh/Q1KhAQ4NRhH6UtKLc3fIEFP1NmQfOdmEfb/3cExU4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619032; c=relaxed/simple; bh=LW3FWQWxnWgJD3Z8QjxOsIjqHu4vcqWf8FWt35UhM3s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=NqwcVRPfdpw/eM4lRR15EqKfVJYX3vqDp+8oYLsrKpprGubP9keRu24Fqul/NQNqUlor9P7TPcVymbUr4A7w6bxXRhg3lCby9kvg3bPLHQknFPcfmaBAxQRoJKXXBci/1WhoJkxGezBG8UbiJz6lQmS8j9ttYiLK6DScnqz7r3Y= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=OKNi4VAQ; 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="OKNi4VAQ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5FE4DC2BC87; Wed, 28 Jan 2026 16:50:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619032; bh=LW3FWQWxnWgJD3Z8QjxOsIjqHu4vcqWf8FWt35UhM3s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=OKNi4VAQlKe7KNV6dBsGnJmgt+HFyFX7ZXCPnWPXokzounb+AWjbWnbHe5qp7vr+O SRewVPKs624exPHz3P9F+CFbfYKACti7W/64ObeNymi6AaIhlRb80it8aTvTETRFZc e7p9rP/HAD7dXfd4qvmLKsb/QbQ1Rn8isPGfSpx2Mbv1CsJP4aecumPmIicmUbegSv WSeItXG7GAcuMjTOGBt463UxMtt3tX+B6HywGGZ2KzmQ/RbFBumXDrKi2hXSEi5xw0 pX7K4xkBbNXuBxH/XW+KvKeUhONBIc2+7NjtGnoubeKFtdHv22SV/U+33Lt91qQU6D vY72B9EeKLvfA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kQ-0000000DArq-2ud0; Wed, 28 Jan 2026 17:50:30 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 07/25] docs: kdoc_parser: fix variable regexes to work with size_t Date: Wed, 28 Jan 2026 17:50:05 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The 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 Wed Feb 11 02:24:22 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 4F0B536922C; Wed, 28 Jan 2026 16:50:33 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619033; cv=none; b=gnxl7OYLK1Cfka48IQuR4FyMYY3dpcI0c91JIdnV7DvwRw3SbGA+/rJHNBUSmx9+pvvTuCiRqyFCIB3wM9Og7IHOl8OL6OZltc7FGf8jayXTguagYuZ64iQ9jiJZNC1p5+GWKVCphpzv3HlH2xdikyopno/nTTkIYqHBhyB5eUE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619033; c=relaxed/simple; bh=Fd24Q1nDNP9DgJx33rkWp9Vbgr/MiR1kgk0MwpCT/0I=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=oV4OWY3UsfVWOD7EOPghbtUp5mOamoik4zq3dWQCG1Bs37yNTaKtGDgbwSaNy5zk+ElPuyXjgCPbOgDiMnFrBjSEh7FLQInuUxGPUMMwRCW+hfqJk/HPSYL0JutmEIUbOVzBg9/VTbrHZa47oydtfG2E3arHfghSnJCIf6b3WQw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=M2WzK3GK; 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="M2WzK3GK" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 236B2C4CEF7; Wed, 28 Jan 2026 16:50:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619033; bh=Fd24Q1nDNP9DgJx33rkWp9Vbgr/MiR1kgk0MwpCT/0I=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=M2WzK3GKPpX6XNswPV1tPHmLNUbg0OoYFItmwL8+7+H6wVJrI+lTkcz92KUplj3uo qqb/TjkCg2jsEj8QjU3xBu/t0s3NsL7EB19gLflwyRQGFzZp4LxbTzzaDvOgP50Uhu t+t5exuqf4ePQNJRtpPYUYrbAMg7PH6UXqHGQuhLWAUzhtCuQkqoJvaLhbqMzf8Wq+ Bfo+/Fqw57BSC89VafMf7EffxH2nnazulOFegJz7I1119FYNEPvq3gCCJDh+r6LIuG Rf19q6F3kSPTem4QIwfWaikg0owW4ys++2/UidymKkpHT1zJOJuz6Q9E5paHeZbLZZ /OMzFVKAjGyEg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kQ-0000000DAt2-45tn; Wed, 28 Jan 2026 17:50:30 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 08/25] docs: kdoc_parser: fix the default_value logic for variables Date: Wed, 28 Jan 2026 17:50:06 +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 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 Wed Feb 11 02:24:22 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 3D851350A09; Wed, 28 Jan 2026 16:50:33 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619033; cv=none; b=jwZ83l89cAr5LU7QRKUHWLkdoFiRfyJPNlfRACo9uNYEpr1RzUed9AWCv0yGXjx4jylHLLpvRixbFZDKqtBGrRfPPJM89F4unN024JPTw1HOG/KWLPKZ1/eurHzE/OzLzcQ6OVToSSP7t8z0Fr3JwoHiDkAFq73rY8oUJAKWj0M= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619033; c=relaxed/simple; bh=kiVn8gJsa15hW54tTb5XhUjmr8gdDA7uMvhSg2gJwFM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=DhXDdr3yYQX1aiI6EaL3QVLH9QzoB4zJexkGdqFmxAydYMTV05JL48dSbL0dO/zhHbtSJ4vkN96oamgwUiTZrg84KBupOVry9HG08Rq5r5wp/XGkqI7OtW+n76PjMMOhKo8il53YpHcowO7Fxz2e9Oa4F6eCk4p8hNKKOSHQYEk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=I1Plv/sD; 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="I1Plv/sD" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1D9ADC4CEF1; Wed, 28 Jan 2026 16:50:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619033; bh=kiVn8gJsa15hW54tTb5XhUjmr8gdDA7uMvhSg2gJwFM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=I1Plv/sDNNLqEuYlpf96nRMOHVctQMqw1/gHSPz20Wefhsilu6hzo6TplPo0fPvzB IZ95bftdX1wqWOUsgGwGHIbXXNtVX8YT98XyB9kDrIDJqeBLxO+QQu5L+T23vvAAoK rnieO7iSHT/5d3BlzchDtUFKMlj5hYRvkmkyfUzzc2ROe+KkM27VQEp+bWfPJa6rzv 6s7VjUAfbxCqG/fLCX877/GrAFAvdDVIZme9Pnssxu37AuYzdWt0xN5J52xWQFjar/ HFH6BksW/Q+6cM8Lt3UVUe1oAnp1aeGeH4DUxK7AaNLRhvpm6mboJIa4g6H+vVQcRf mNTfSACMShHww== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kR-0000000DAuD-0xVA; Wed, 28 Jan 2026 17:50:31 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 09/25] docs: kdoc_parser: add some debug for variable parsing Date: Wed, 28 Jan 2026 17:50:07 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab 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 Wed Feb 11 02:24:22 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 F3DD436EAB7; Wed, 28 Jan 2026 16:50:33 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619034; cv=none; b=RM0cMl82VhhMyFRgGB8aZw8M2b9VtjhQDaYTGZwN6yO2tH1VaB0bV2xY0Nm8yLlOwFWF7GLxKq42L3qh+IvyaQY92REdcgrBAmhpIjsqvxhnxO6iFn9/ctlgGFfcp4AtBLlrKgAAmjlUFNADPYQJFAMVjlJxc3B+dOmcVk97CW4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619034; c=relaxed/simple; bh=BGmC9Ub+EwkCy+50Wez7U2hU9ogTq3RfJ1GhpzG3syM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ukXbUxX1opmGEPJUmlM05Zc3JVo3QDbKmQ52+eRo8eZuOaIWf1adBKK6qJwXDTy+6sI5qHQkZ0EgcpEFDsTo1/rPZdGgsHYnNI9SmFM7XInwqupYrTrR2G8zqtyDxbFOoUuaZOkQVSrzKZ6Cnstz3A2lKhEN9zdOfIvByM1Iv20= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=PKIcnr7v; 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="PKIcnr7v" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D1452C4AF0F; Wed, 28 Jan 2026 16:50:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619033; bh=BGmC9Ub+EwkCy+50Wez7U2hU9ogTq3RfJ1GhpzG3syM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PKIcnr7vb6QYWKKmZ4MGNRfluhiMvv/ZcGy9MRlgaglVwusL3E7V9SXbnHp7unAus FaAqm6AK8bdWSag9J0h47RjwmEbhuXZNCFlGtJgzLPYCtYNUOjzjXyRT+m1f+Qye+L /oSX5sWi2me8ioxXIY22KYg4zPSHfTZrIJTILp0+pFN7rc0GO5wx0Zfz8fr6Z9Y95e kMCeE4LlYLU9wlOg2xrIKQLMkAWZN2lWJ/iI8oaVry73ULwb35sXtdaBn9FXthlcNi /9aL5ZqrVPJS4sjDYkRRCsAwWeZv6ZSho4TAK66ZdtXpqCqDIZVf/6YuiXrsTiJJFH 9zOOQk4+KDTfw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kR-0000000DAvP-2CUa; Wed, 28 Jan 2026 17:50:31 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 10/25] docs: kdoc_parser: don't exclude defaults from prototype Date: Wed, 28 Jan 2026 17:50:08 +0100 Message-ID: <42169cd386170c650110a62a4fe467ecf83d757b.1769617841.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 Wed Feb 11 02:24:22 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 ECAED30C626; Wed, 28 Jan 2026 16:50:33 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619034; cv=none; b=fK/+ZPMDYxtoMzqg80K7Ju28Si5NwOlHB09yLzlyGmoiS3cPRAKYBiRmSvSm6gx6LwjmtCtyPDk/OOkwPr6fhcK58o22vpfEIVs8D7j7A3Mza7yBSCNFYmUmE89RPdFnVFy80WGwcr/NiryLGv5BS59UFmcSfHHnEIO0mSzzeY8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619034; c=relaxed/simple; bh=+PHSHQk42n1s2eoXmKBeCEHsRg0AhUmcVaeG8R0cpiE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=fjJUIF/9gGguv+OenGW+FgsjZC4Sbh70ANqStDr7/YZ+IK5rRLAn9pr5S6H+lugR3SxW0WZOZ31O/nVn/D+3lBiN/Dfs8+RKCPDmttAyqusAC5m1mR65hoa588jMrispr37kSplfb47VN3MrfiL0lhRjM6MlMHh2CZgFDuGyZhY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=fUDxbWwU; 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="fUDxbWwU" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D0229C2BC9E; Wed, 28 Jan 2026 16:50:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619033; bh=+PHSHQk42n1s2eoXmKBeCEHsRg0AhUmcVaeG8R0cpiE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=fUDxbWwUpvODFtK7Bn0IDVqUo4wRl4FZ2y9tMSl8n6OmeL6FaTaJaETZ5HletL/27 u8zCMurLOPRvtO/7H7AQe96Wf8qEBLTNx0Aw36SaM+fzSuEMHw5ZCQhwyBXtywuX2E ufdxiWhrr5oS2RxdPl1QJlXpIHzMqbDUpLV+WhA1dTiPyuq+nHo088Q0At0522ASsm Ts6u1Lw7NlGhW7jxOvGMK7DM6rvGvPdUC/qyPO1+N294RvCj7H7W9lapR7ZCd4ciSi wHdhYOHvfvIYkRUJsrqDaLONAREIdqxtJMQE3N86mlUzpNSfM/2pfGVddAZI8cJ4Ry xCQHCMdaN32JQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kR-0000000DAwc-3XJq; Wed, 28 Jan 2026 17:50:31 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 11/25] docs: kdoc_parser: fix parser to support multi-word types Date: Wed, 28 Jan 2026 17:50: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 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 Wed Feb 11 02:24:22 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 A5E9A371072; Wed, 28 Jan 2026 16:50:34 +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=1769619034; cv=none; b=CUgeaN2SlBxmh2y6LAk8j3CIP7oi+Gd2aeqRFbegDYqSja0OQ8AMl+St8oO32o/oJXRakCjmUDvOePKa86dkZC92o5avM/VNgjLW7KCIuvKIgg5+VUiYE0p/3ZjaaFQGN6gQ9rB6bD4tlsCvSpdIcKkc/+zd7mT4AwiLAt/jQsk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619034; c=relaxed/simple; bh=YVVe7KRzqnppyn56cGxlJApAQyowTVAxdXTJwpP28d8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=DlHU78XcHEDmTraZEfHTK1SHTXKmEwyiVyOjoa/AgWUdK6peQJOUL77mQhbnd6WCYnzPn7KRw01aIklUSRy9i3EMCs6YA+AGqFKnCsKxotwqicy+JRhb0Eh0iklYsgr8NB2NGKeCvR4Qs4LDWJ554keEOjSjLMzXRnHpquUVqrY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=u9wZo/gM; 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="u9wZo/gM" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 72E0CC4CEF7; Wed, 28 Jan 2026 16:50:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619034; bh=YVVe7KRzqnppyn56cGxlJApAQyowTVAxdXTJwpP28d8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=u9wZo/gMca0BPI3ua8PMHR0Oryi0fX51PLksQhUhVfiZo6+UAQGPy+4R//p4QEqC9 blaeNAIMIA9bDX7MmmS2225YB3YQq4MkfPSptohmJiHrmGEsSK5dfhb69mgl50ezO8 3DLiHNINq4MvKt0HNYWLkZIkfp5wuuY6kJrWyVzT7hIRWA5xz1IQF5B9CaMbLZMDG0 4BxzfFCWTXkgjy8uPNygVxnBQVwhLEP2mzF1sLgsJQioG/WPgQGc3p1+8YZL4IzrSk VFDD2OSxeFupft5Ix4d8+qAvbSLaLU0gWF8vYw9HIV0/oEppQU6wGt5EwW6iQTqyOW FYFn6P6eo6Kcg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kS-0000000DAxq-0iTm; Wed, 28 Jan 2026 17:50:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 12/25] docs: kdoc_parser: ignore context analysis and lock attributes Date: Wed, 28 Jan 2026 17:50:10 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab From: Randy Dunlap Drop all context analysis and lock (tracking) attributes to avoid kernel-doc warnings. Documentation/core-api/kref:328: ../include/linux/kref.h:72: WARNING: Inval= id C declaration: Expected end of definition. [error at 96] int kref_put_mutex (struct kref *kref, void (*release)(struct kref *kref)= , struct mutex *mutex) __cond_acquires(true# mutex) -------------------------------------------------------------------------= -----------------------^ Documentation/core-api/kref:328: ../include/linux/kref.h:94: WARNING: Inval= id C declaration: Expected end of definition. [error at 92] int kref_put_lock (struct kref *kref, void (*release)(struct kref *kref),= spinlock_t *lock) __cond_acquires(true# lock) -------------------------------------------------------------------------= -------------------^ The regex is suggested by Mauro; mine was too greedy. Thanks. Updated context analysis and lock macros list provided by PeterZ. Thanks. Reported-by: Stephen Rothwell Closes: https://lore.kernel.org/all/20260107161548.45530e1c@canb.auug.org.a= u/ Signed-off-by: Randy Dunlap Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 21cc4e19a1e8..92b550189988 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -81,6 +81,8 @@ struct_xforms =3D [ (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ' '), + (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ' '), (KernRe(r'\s*__packed\s*', re.S), ' '), (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), (KernRe(r'\s*__private', re.S), ' '), @@ -165,6 +167,16 @@ struct_nested_prefixes =3D [ # the start delimiter. # function_nested_prefixes =3D [ + (re.compile(r"__cond_acquires\s*\("), ""), + (re.compile(r"__cond_releases\s*\("), ""), + (re.compile(r"__acquires\s*\("), ""), + (re.compile(r"__releases\s*\("), ""), + (re.compile(r"__must_hold\s*\("), ""), + (re.compile(r"__must_not_hold\s*\("), ""), + (re.compile(r"__must_hold_shared\s*\("), ""), + (re.compile(r"__cond_acquires_shared\s*\("), ""), + (re.compile(r"__acquires_shared\s*\("), ""), + (re.compile(r"__releases_shared\s*\("), ""), (re.compile(r"__attribute__\s*\("), ""), ] =20 @@ -195,6 +207,7 @@ function_xforms =3D [ (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""), (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2= "), + (KernRe(r"__no_context_analysis\s*"), ""), (KernRe(r"__attribute_const__ +"), ""), ] =20 @@ -204,6 +217,8 @@ function_xforms =3D [ var_xforms =3D [ (KernRe(r"__read_mostly"), ""), (KernRe(r"__ro_after_init"), ""), + (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ""), + (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ""), (KernRe(r"(?://.*)$"), ""), (KernRe(r"(?:/\*.*\*/)"), ""), (KernRe(r";$"), ""), --=20 2.52.0 From nobody Wed Feb 11 02:24:22 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 A5F6A371073; Wed, 28 Jan 2026 16:50:34 +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=1769619034; cv=none; b=G+6erNdu/3dqK0Qj6rKtVKLX7iHiJQ81n7DXcv4el95gXsGjvno3LgRLQe/Rv3BC72E+CC44KqM5Sc5wdGqsMkh2zl1i6F5AHIIJ4J7U1GLY/UirDBkkruFhGT5yHvajp+vLkBwCYGjmgjz2N5dy+W+Va8PH3rB9dE2ByqMlEmo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619034; c=relaxed/simple; bh=FAGo3vp1MYKDT8O2fN+VyX3S2nX5qeOzVDn265Hyrg0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=EIS838pQ7ItFS6NQG/dkRCHQsc4L/EezXfn312BXS3hMbG9yxUYjJ4C/QCuy4Fa4W7hMa5vj9twGZQuzYqLBtI+xiXlYeQjZ9ebGV1AS10G6DrQDPQLyCi1W8IXcjaebLVY6PpN6zAXgCdY+NpfUQq3J7JWZ7fF5lF6ufeNYM3M= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=iTNz+5Ib; 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="iTNz+5Ib" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 72557C4CEF1; Wed, 28 Jan 2026 16:50:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619034; bh=FAGo3vp1MYKDT8O2fN+VyX3S2nX5qeOzVDn265Hyrg0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iTNz+5IbtqRIFaEc3wxSMvLY4SGuhWXsaG89cnQ7zvyLdiQjiwGK7SyqAh736rE+N bq0nFWFbkQyIclENSlnsAslMX0nndJLWweiWGEq48jLK77CMmR2n4xjkMP4r6inXuY hYlDZHQhXwoqNzH11802AHQVgs/ggt7ggOEy54P9JTAlpf7HjSapRTZoAm7YI44Dx1 tLaQM/QP4uoFa7DpygKbwfbNMMm28MDTuJ5ixH2QY3yYzx5O5b3ZdWmYPbxAyQ/Dop H8Yu30QB9FuZUfqgruAVZWYH7beCrBSDQq0FWP+Nivr0nFzBUuOCgTJUmBHVjBZC8m w+hyavb/Kdgcw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kS-0000000DAz1-1wI7; Wed, 28 Jan 2026 17:50:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 13/25] docs: kdoc_parser: add support for LIST_HEAD Date: Wed, 28 Jan 2026 17:50:11 +0100 Message-ID: <7a254f627ed79e2a7ffaf3e91bbb5ab269595d20.1769617841.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Convert LIST_HEAD into struct list_head when handling its prototype. Signed-off-by: Mauro Carvalho Chehab Acked-by: Randy Dunlap Tested-by: Randy Dunlap Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 92b550189988..33710c4be145 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -219,6 +219,7 @@ var_xforms =3D [ (KernRe(r"__ro_after_init"), ""), (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ""), (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ""), + (KernRe(r"LIST_HEAD\(([\w_]+)\)"), r"struct list_head \1"), (KernRe(r"(?://.*)$"), ""), (KernRe(r"(?:/\*.*\*/)"), ""), (KernRe(r";$"), ""), --=20 2.52.0 From nobody Wed Feb 11 02:24:22 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 27A5B372B57; Wed, 28 Jan 2026 16:50:35 +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=1769619035; cv=none; b=QyDDMMBB0nXMUKUo7IDqng31A4dUuoyoNNnC7lGLyFzPugA62iYgGxfhVH4KkZNruIjNDbWXawZoy8Ywv2OzTFzH9xve7UTx92vOyFsFFADW6gXpQt8sYqq/n8BfUoI0Xqrl6F3x5pQaN7oTMmsmQi8xLXy6OL5HWYTTbBws9XM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619035; c=relaxed/simple; bh=E/NkbGhW79SHOexEJ6i7PkHNPXwMx9nBDdwcfT26Xts=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Dyy+CKekGrIo5wEuZWfaVr0oRtcoCTVfpid5COwCAhmhDNrf/BY6xw2V6Ktc19jkkgrdg1Nqa9LXY6b7ZROJji8DZZTBy01ueRFj6xWpLJ+yNfKrj0vP4G8b8Plx8ev9cNCjrnNQ4DrUxuyXygZywf9Am0GIamKKbWat5+Q4xVY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=jgEs8KLT; 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="jgEs8KLT" Received: by smtp.kernel.org (Postfix) with ESMTPSA id EBE43C4AF0C; Wed, 28 Jan 2026 16:50:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619035; bh=E/NkbGhW79SHOexEJ6i7PkHNPXwMx9nBDdwcfT26Xts=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jgEs8KLT+fSZYa8scXr97qocIE/yUTDBVKxLaLukMi1ByFu5mIxBSfoayfdkTbHU9 gvgHyPzicYKXhL1Fqtab7yXDC2reL52BB04G9w6xCCU4uxbWKsqeobFn9yoWmGQahZ MDP2GsVGXADgVlA9PcbBI7USYzfFw76k3H3Tnu413mhONC/yhJTllDDDW3ipC/xze2 WBb+x9tqbnuAh5+4/UhzPRG3n5/sGcCNCzUDBvLEmbGHJTBfixcTvXb+71jdHEVbrM tI+PvhWJ06HdUJgnMnZIpM7AQGuAQihMb/U5YsMiwcd3j5TDc9+VdVqfTk9PkR/C0H YvxZSHqulIc0Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kS-0000000DB0F-3O3I; Wed, 28 Jan 2026 17:50:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 14/25] kdoc_parser: handle struct member macro VIRTIO_DECLARE_FEATURES(name) Date: Wed, 28 Jan 2026 17:50:12 +0100 Message-ID: <1c649fb1db817040e1641a3f8980f15787725eec.1769617841.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab From: Randy Dunlap Parse the macro VIRTIO_DECLARE_FEATURES(name) and expand it to its definition. These prevents one build warning: WARNING: include/linux/virtio.h:188 struct member 'VIRTIO_DECLARE_FEATURES(= features' not described in 'virtio_device' Signed-off-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 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 Wed Feb 11 02:24:22 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 2866F372B58; Wed, 28 Jan 2026 16:50:35 +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=1769619035; cv=none; b=edwBYG9Vs1nsuu3jYtyJ1BSDtAAEXekOP/hYJz7r4DRwE+g4XS+Zh0yGHJb6uec4tSawN8BdVxzL7pxMj98/9aK5U4rpl7C49dkmvsK7pBDe+FTpuwMTqo9ZBvuKWpzZLaxBrcTX9WMxfgBQxfh2EHxNhNLTNg5PkRiILvJTlgg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619035; c=relaxed/simple; bh=LaLUXoY/KS6WIRVp9iorgFncFjJ1rGpIWKLw4YbQxJU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=LED4iHXPCG2t35lDHOtkKuNP7PPfyXMQDO9d8EeTCKnmW/7zadtTmYa7k2w4ZsG41hVAhvj9Zvje8oAdktcZmMo1yciGIKVE36BcvBL4loDxcJLb/0CZAOeQ3GDe8lzilW3tj4kTKTdcKZvUnz7l/KDWzxMouvird6qxBoQTlVU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=MAdy0Pn4; 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="MAdy0Pn4" Received: by smtp.kernel.org (Postfix) with ESMTPSA id E6E3DC4AF09; Wed, 28 Jan 2026 16:50:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619034; bh=LaLUXoY/KS6WIRVp9iorgFncFjJ1rGpIWKLw4YbQxJU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=MAdy0Pn4PxMBzSJDBYcEr2AP0/IM48hX+BjDM49cjB/+BzdvguBKB2hNMO1u0NqP7 4SmciDVlxhTVqqriuOudMQi8GYQbH4Xy0RZ0FmgmzswS+auffCPCrYdLKDS1NaSD8V 2f2lJpVto3DW99L5agFfQJu8lSzSfceYwuKR83ClL0nOQ5H3jD4Fh1gAy0DTjXfkFO OcN+1L4D8BImAEk/VWN1ssCz4LI1sPJuPapJwM7w+vJJ+NGbhRpboig/+g9Ya/p4Ul jFpaZiVxoBtbUeuQJHfbrQAhXUBzEsUIClExRvCwVqczKtkqrxG1hsFn/MeGXBVUWn j+dwWzxZgAhBQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kT-0000000DB1Q-0LmB; Wed, 28 Jan 2026 17:50:33 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 15/25] docs: kdoc_re: properly handle strings and escape chars on it Date: Wed, 28 Jan 2026 17:50:13 +0100 Message-ID: <934f61b22277dd5575c77edde96dfa7a98c8d79b.1769617841.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 Wed Feb 11 02:24:22 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 5C07C37417E; Wed, 28 Jan 2026 16:50:35 +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=1769619035; cv=none; b=spVQ3NuysFmWIGEv/JtwE2uYQvnUOcBVKCHNXqDJRfClfrKEjoHL4A302dfNJQRv8xjSd5Yqe2XA8O5phm99Gl/asv6Px/wEXH6itRlh6B4ItXopeVlULHJMPrYrFnu0M5bztf0MN8SRokVg05JEFPeV/1NiG+psepNxDdWB/0M= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619035; c=relaxed/simple; bh=ARtXC1+LQ3gRcThfqj9ksV0v7BRfUWm6DuW6ltrwGzE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=hHpHsX1MfvQdVQ4WXSYV3p/UpZnLqV4zj8279GfE5GiPm3RvYLDIgbybJ4EL0gpjAwfLA3Y1KI4WD1wyILdKtIkp4bfQTICBUKGhdAZRvBXFRUYTtMm0tnujqGIiL3xzjg/Q9R6tu5ktrNZK2rBfM4lK3Ae0GCSBRLtt64y6wtM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=rBNzgPTj; 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="rBNzgPTj" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3DA6AC4CEF1; Wed, 28 Jan 2026 16:50:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619035; bh=ARtXC1+LQ3gRcThfqj9ksV0v7BRfUWm6DuW6ltrwGzE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rBNzgPTjrZhoGqDIQIiY+NXA39lbLYyqKMf9BI0t9Jy5mZjv+t55LMKg6QSQKbgCg 3WrUkbkcvzxmimjvvXVS/hkiCDaAP1MmUsI4T3hXXIWv/cve1RHlKBK1uuBTSNeXl8 ZvwZfmubafYJBzaYiP0MEbTExnpWUTQpxtjiC/U6JWcZ05AzOhv9S0Yl42rPLPK/ZL nNcIefSmEVlMiEe03yazL/NGpkoOHi3nYktqRngA3UF6Khf0UAx+FRMUX3lR6jALOq mByAd4NZ3XkyE1KcAtbhNvJTjMLlbMR8CojwlgwBFg1Jwcx6zgqaEwWXOclSv/L0DA mOxCKsbId+Etw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kT-0000000DB2b-1Xnf; Wed, 28 Jan 2026 17:50:33 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 16/25] docs: kdoc_re: better show KernRe() at documentation Date: Wed, 28 Jan 2026 17:50:14 +0100 Message-ID: <56e007be74d8572c7c695d811e72e70447c466aa.1769617841.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab the __repr__() function is used by autodoc to document macro initialization. Add a better representation for them. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_re.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index 1861799f1966..f082f82bad67 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -52,7 +52,10 @@ class KernRe: return self.regex.pattern =20 def __repr__(self): - return f're.compile("{self.regex.pattern}")' + if self.regex.flags: + return f'KernRe("{self.regex.pattern}", {self.regex.flags})' + else: + return f'KernRe("{self.regex.pattern}")' =20 def __add__(self, other): """ --=20 2.52.0 From nobody Wed Feb 11 02:24:22 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 F3EB5376461; Wed, 28 Jan 2026 16:50:35 +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=1769619036; cv=none; b=jqVMTu4/CrdtJ8r1VC752Z7MT4N/E+UATJbkmXnvkiSm7xwGQA7zkpiGgidhmXmB0f3QzcKR3ZK6jTUY9Ft1l7CZbVbsWfwbi/ODcGDTV/dXMcyBdJYtBOELEsrOo9oiZT85OzwNiuSKmsh4iYEE8WPXlASv0UlQNV/4gvs191g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619036; c=relaxed/simple; bh=gkns4e3uFG3waqW3gYcl7M5Q1Ru6AdLSMlaBiCnqdQM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Lb9bl36EwAwC+YXYacS4C7nujjsZM6cyGq0RTeNl3J2+Brk2/Cs+GpzjyYUnUaiMYMLyUMggTfJLWSMIOqFctKTye9jlKoWwZXqxyWcW4NL+PPenO/FLRrCtbiDE+IYP4UUZ26rVli7Wfo2kGTtorFsCwz+0zS+kiV01NwYerSY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=JeZbi13G; 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="JeZbi13G" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C4C06C4CEF1; Wed, 28 Jan 2026 16:50:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619035; bh=gkns4e3uFG3waqW3gYcl7M5Q1Ru6AdLSMlaBiCnqdQM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=JeZbi13GwrgsGYtpPX4XumjmqUTcWoMbNC7coPCjBC++DdYd/ZIjEs7oPtwtCD2ec iYu85X20yNh9re5IieGZfJ+0PelHr0Nb3Wom0j3Ccf9JTjXOswoeGSOOX2rB5o2wm2 bQPS9/SaJm1it19zLoXOgibNlG8BrlWgZM4HQ3xxQoBZPp/gZNOeLQg8HhsiX8RZff fW9uP635BswyPr/K4OGEpjqIOO3utDH/V7FsZwlS+72TXrxJE1l/l/KRXLes8ad9wf msDFRZuixzV66dpXFw8NXVEcnNstAaeF1AeNBpT9jiHlENNEDnWGhiUT2c1Z1m9KNE 3Yut7q0em1qEQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kT-0000000DB3p-2pLf; Wed, 28 Jan 2026 17:50:33 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 17/25] docs: kdoc_re: don't recompile NextMatch regex every time Date: Wed, 28 Jan 2026 17:50:15 +0100 Message-ID: <0eabdd8b9c895230b98b289ab3352303b816858e.1769617841.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 f082f82bad67..b6e11ee0be21 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -81,6 +81,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. @@ -116,6 +123,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: """ @@ -165,14 +182,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. @@ -202,13 +211,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] @@ -229,8 +238,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 Wed Feb 11 02:24:22 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 102BE376463; Wed, 28 Jan 2026 16:50:35 +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=1769619036; cv=none; b=BB2mEZxqTHfDpm5LQQhXz6eSUpEH9I6hfE2jt8Y61uoYkKET9FputaxAGAD70svZo5YUUnq9KtAUrSL863uvTzQomPyDaZRMJdpUkZ6KQ8O41W0wLutQVqXqUPYbo1Yr6q48SXGqU7yR0nclr5+qTvBOopSrKx07+mMcwCaEH/8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619036; c=relaxed/simple; bh=eEXbBuQJszefL3B/0u0xuMDgFhmsCIKucbWpvC7EagQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=uoX4DQcqIfNoMb/N9ERHVjUE0AaCGuyTRwxSwof0HXzY9nQrH/uHJM/kOr9UsGcarErsCCeYAxLol5oimIWmqgm8knI93WdpDPMe1XlaTpWYVnSLNEj8TvPZw9GbYOiEDZznp6uFRujA0BDy9ovS2aw+lVBxGAn7LwF0dV7RH1A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Ietd/thr; 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="Ietd/thr" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C9A9FC116C6; Wed, 28 Jan 2026 16:50:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619035; bh=eEXbBuQJszefL3B/0u0xuMDgFhmsCIKucbWpvC7EagQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Ietd/thrp+Wgkn2FFcx+NtiFEntfcPxqSCbgnMI1Np48edS47DIEacKLeZrEbEgTi /N/D+IQp/zYdnxRFSbMOkAp4sgVKIyPBsNiQqz3qAja/7y4VaPdsbUGxwQeS5v07ZT zMRKQHtOdNxh6Q01gndXZlvisf55hyjj3dLKkTITU+e8CTEdLkRbZn1czO0EpuxECe bLE7UIzYBz9SO/y143/sRYVssD5+i/2SxI0CwwgMfj1fQWE1OI6EXR8wLXbUdPIYqx 8Tss/yqO6ap9UOfyd0K41+5VBldEbNNdn1RRgljnvivP8Hn0EqipVVWsIs4YBoWH5H 9dCLt2k6fynFg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kT-0000000DB50-48Df; Wed, 28 Jan 2026 17:50:33 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 18/25] docs: kdoc_re: Change NestedMath args replacement to \0 Date: Wed, 28 Jan 2026 17:50:16 +0100 Message-ID: <323b4c67ae7fd241670ef0b5ff6eeb10d968415e.1769617841.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Future patches will allow parsing each argument instead of the hole set. Prepare for it by changing the replace all args from \1 to \0. No functional changes. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 2 +- tools/lib/python/kdoc/kdoc_re.py | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index db140363104a..4d52a00acfad 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -160,7 +160,7 @@ struct_xforms =3D [ # is allowed. # struct_nested_prefixes =3D [ - (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), + (re.compile(r'\bSTRUCT_GROUP\('), r'\0'), ] =20 # diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index b6e11ee0be21..28ca5032f40c 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -271,8 +271,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. @@ -288,9 +289,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 Wed Feb 11 02:24:22 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 38D2437647F; Wed, 28 Jan 2026 16:50:36 +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=1769619036; cv=none; b=VhUb1ZE9gZbioRC7ZhhDmxvBVCkSnTdg82qZsP0fwDUmI5x7xnYq3BE59o+Lo6LkUEXnbOc+xZhFpyvCFsrZ1Ru5EU2FfS3osFs5+6M4C9y1Xr15arzfAuxWNCctVosh3azo6Hidv6ZWVvh8UK+bpiaBaqmwpFUjjsU76wssHIo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619036; c=relaxed/simple; bh=0ot0R67HaXRc1V/itdeBaIZAxY2fnyJVatiNePQaLeE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=WXn1zCtEHBJvRigOL0WzwIsU9yBTEo1zUh7d4DGzHqLBCCFB4ox9XL+Kdcg2a0cB6AluOnJb/fltqgiyYQcFJrO0Bag0dL+rFa5tBn02Wxm8NmNPfW1vcPGT0kqaOPDtG40kif1hM7vjcJ8OGwrYDLipC8//LSIFVABmz2sqUwY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=LCWNel7W; 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="LCWNel7W" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1AFACC4CEF7; Wed, 28 Jan 2026 16:50:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619036; bh=0ot0R67HaXRc1V/itdeBaIZAxY2fnyJVatiNePQaLeE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=LCWNel7W+vLM6dl/jinSacwdQxpfjma+Mnc2KSAAOYfec6Qvlw8DJOtrX6eKffEVv t5xlaeZAN8mnyGOXevISJ9p50QMyZDe3d9cygCfaFOKQEyfTJ4/DgiBfAv44qS4SMX UYXxWwiEhp5OJrf73W/gnMJcanu0nwCjOc19IiyFpnB2fKte+fWpzK24b9BLvh/iMd CrMZxvxXLV4kzEAInJApk+N6Ma+aAsx16YoBB/LEXyHU1VfwcXRUXKqFsY9WidTlKC NYNPcqqpuRmFKGae/I/KfL3i7ZHLHtAdaIu5kzLHIRLhEyavK5qXRXfzP6EVBfX2HF SRxv+bO8kaFPQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kU-0000000DB6E-1TqQ; Wed, 28 Jan 2026 17:50:34 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 19/25] docs: kdoc_re: make NextedMatch use KernRe Date: Wed, 28 Jan 2026 17:50:17 +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 rejex and use KernRe to keep it cached. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_parser.py | 55 ++++++++-------------------- tools/lib/python/kdoc/kdoc_re.py | 15 +++++--- 2 files changed, 25 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 28ca5032f40c..aabfd6c4fd71 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -182,7 +182,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 @@ -204,7 +207,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 @@ -252,7 +255,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 @@ -260,11 +263,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 @@ -283,7 +286,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 --=20 2.52.0 From nobody Wed Feb 11 02:24:22 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 DACEF376BF1; Wed, 28 Jan 2026 16:50:36 +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=1769619037; cv=none; b=OQVPXSIv3jPSEcUu3UtenJRbONY/gfC2d82skeyUOq5TAKYuKwm1+5Jc3HTPcvbzcWFxoN36HqgaiQKknvDK8Wboc4c3Ckl0PAfwIfhSwNQbpQvwP7YEX4RcxU7coCFyvodkajtxt9sMUgj3yNIwKdfKIDy9NTOg8NJsLGszzGI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619037; c=relaxed/simple; bh=9hX1oywg1Y3txaPPZEQtrG+JM7sUb7c+w2+8n+ph75o=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=cNt4yARo5qVQEPZgrvKm+rglaiSyBgoBcha754z8rSOFploXVDLf1gmtCLJTyPQxHCdq8KbkrMjZ1AG68ig1A15NItQRYyyzXqrxyRvXkRTJ1kjjhjO++dCXDFvH2YC5Ghca0BlDHHMVpuTmV3dERv88okvaJHc71DZggErJkIE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=uB7rv6MG; 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="uB7rv6MG" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B05F3C4CEF1; Wed, 28 Jan 2026 16:50:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619036; bh=9hX1oywg1Y3txaPPZEQtrG+JM7sUb7c+w2+8n+ph75o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uB7rv6MG0D8lfxVU3F+negR4Dm2Cv7s/5bWYbEWoSFTAka2Sl2Wq/ECE31sw+DYPB ee2wLL7tLY7FFA1iEGUECqTj1olYIenIb/Og65iFul1SPvl325JKB2zZNGTZYuSpQd hLtg8Tc4WMm+oUHsQ8RpX7ZgHo2U624Ugs0tmlT3cLdAUOo/CYz2iprYsfRnxHvX7H 6cdtgTrjDX9HmzofaxUpdgM2B13upvvGgL2YvV4nt7luPssD+JiPhm6EHHeY1L6eMA 1LuF3TK2yuWDfuS5tWsWNixNVPmkTV8FoGv8RuV9DRVlswMpl3vfysYdykBMpLEVNl S0JaMjyDQPlbg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kU-0000000DB7Q-2nh2; Wed, 28 Jan 2026 17:50:34 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 20/25] tools: kdoc_re: add support on NestedMatch for argument replacement Date: Wed, 28 Jan 2026 17:50:18 +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 | 61 ++++++++++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 2 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_= re.py index aabfd6c4fd71..f49a568b9155 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -267,6 +267,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: @@ -292,9 +345,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 Wed Feb 11 02:24:22 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 7C2D93783AC; Wed, 28 Jan 2026 16:50:37 +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=1769619037; cv=none; b=DACiLxlxyV2sFWLoWu56ZXQewTauNIyht9i/Kzsvkr1Ti9F1aefRf6yU8nrY3Awj1n+f5T3BwYRny+Qikf4WVvAiXAM5t5iEf0nKa0hVN/9CIC9h0Qqb7akPB+7OacEZXqpfbuRKF4xv37KecSpJKp4I2zF4/NEP2M0x5YzoRpU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619037; c=relaxed/simple; bh=8Si4R7luS6C4MLjJjbGsfuRnLBtzGHb8hxnSO4AU+LY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=kV+9UCgWU1WPfjAb5asu2JKVLFUCMO8bgR32ZoOfv7U1dPlwuh8UBd37AK+4vbzYVYAXXoecWbDZ3tVERJvV0gQa0tCpHST+04TjRV9P75O4zzCNNST5GVO/H4XgjUsDKwyebJZpQtnh+sOl1n5wA39JxzGHLVdYhHv00llXuxY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=GLja331k; 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="GLja331k" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 174CBC16AAE; Wed, 28 Jan 2026 16:50:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619037; bh=8Si4R7luS6C4MLjJjbGsfuRnLBtzGHb8hxnSO4AU+LY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GLja331kUQf6xG51/UtHIQYCDNRw3Sm6SVEftClY/9jZ+WwNLgL7/Sr4mhO6nft3a vf6Sm9YrtwKn7bu9XRsWyMZYoW6bCayoY/f02ardAlFczxJVqhCpaQzwloG7LXpraa 61hbDYGkPo9x0sS02FEDltclU+yYedyIn1LMtao5iu/EIfvwoxNAG7B/wpKqOraDNy bOXfw4DE81TZ5C0fv1TDy4a2B8rIw34z9/4LHE5zZ6MkRtiLJ0szj8FWRBVEs2FndA bt9YRLkCEAkOUTUFmqZrfNQnHDfrNe4PbdH0BuE3B1VyFNjvm1I1plfG9eXm1pOojH RWX5RLLNAhQag== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kV-0000000DB8d-0QVp; Wed, 28 Jan 2026 17:50:35 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Shuah Khan , Stephen Rothwell Subject: [PATCH v2 21/25] tools: python: add helpers to run unit tests Date: Wed, 28 Jan 2026 17:50:19 +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 --- tools/lib/python/unittest_helper.py | 293 ++++++++++++++++++++++++++++ 1 file changed, 293 insertions(+) create mode 100755 tools/lib/python/unittest_helper.py diff --git a/tools/lib/python/unittest_helper.py b/tools/lib/python/unittes= t_helper.py new file mode 100755 index 000000000000..e438472fa704 --- /dev/null +++ b/tools/lib/python/unittest_helper.py @@ -0,0 +1,293 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright(c) 2025-2026: Mauro Carvalho Chehab . +# +# pylint: disable=3DC0103,R0912,R0914,E1101 + +""" +Helper class to better display unittest results. + +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 + """ + 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, parser=3DNone, args=3DNone, env=3DNone): + """Execute all tests from the unity test file""" + if not args: + if not parser: + parser =3D self.parse_args() + args =3D parser.parse_args() + + 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 + loader =3D unittest.TestLoader() + suite =3D loader.discover(start_dir=3Dos.path.dirname(caller_file), + 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. + """ + TestUnits().run(fname) --=20 2.52.0 From nobody Wed Feb 11 02:24:22 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 8BDBC378D8A; Wed, 28 Jan 2026 16:50:38 +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=1769619038; cv=none; b=LhAQH+ZaEzdP9L16bjxD/i7QLg29QEOexjX0xnHVQvfhUSjU3/7IaAk5Pu5VTaRzmsAE6Toyb4nMI23kZ7hTBV7ywnz0cW5bwsw157lLqMXWGs12Y7U/YvRu20pCKU9vPCEfPyrUBcb75Dlk7WI7ExgUw6ZRtXBfP1DQVOH84OM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619038; c=relaxed/simple; bh=pYNTYqwz57IhqZvQF9WXqa3KlEvEIfaBjfkBtr3E1OY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=hCHze2sR4CNeuoN3t2gYGcXhHa9xd87rLRRHWaYozvG0+iLe5akrZUeBbsY9M4tLuR9YJHwqIYPMcwFRiv4ya4qQMLar4Tb2kg0IuqZ3GOmyXZurJe2kr/WKI0g6YRE1pWqr7OhW/97jlZODTE3KLr4UcC4lkxeGZM78+YoSnTY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Hj/UBkSu; 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="Hj/UBkSu" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 054E9C2BC86; Wed, 28 Jan 2026 16:50:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619038; bh=pYNTYqwz57IhqZvQF9WXqa3KlEvEIfaBjfkBtr3E1OY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Hj/UBkSuO9Z5o5win3cZIb0qLF0YcfNjT9EHWyrhnycD5wY/BfImtYn3YjuFZw0FW FnJ1WKPQnWtZ0ZC3xwyJ9DGZfVkgOp/7G5qIZ9+iKcQTQ3v4UHRBwMFhphaJadug23 Z5Mzs0Pq9399fTZz3AfOpKj8cCf+6dH9OL0swUS15MzVs0j2xIbSjJzj58gndRQUCq yq5wYQ4RwAhoF+A2ZUbQPJr2i0gHcvPPL2jkVfAEu2fL1SPkYaVN63QUbUs1C+n8cb bqwS1oKAKDit/N3jV5RmevzlntlmXB+hcqjQ5EBZ9yuwA/mQqPKyimHdz/MC67rmwS ecXmNJmGiypqg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kV-0000000DB9q-3eDF; Wed, 28 Jan 2026 17:50:35 +0100 From: Mauro Carvalho Chehab To: Alexander Lobakin , Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, "David S. Miller" , Alexei Starovoitov , Daniel Borkmann , Jakub Kicinski , Jesper Dangaard Brouer , John Fastabend , Peter Zijlstra , Randy Dunlap , Richard Cochran , Stanislav Fomichev , Stephen Rothwell Subject: [PATCH v2 22/25] unittests: add tests for NestedMatch class Date: Wed, 28 Jan 2026 17:50:20 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The NestedMatch logic is complex enough to justify tests to ensure that it is doing its job. Add unittests to check the functionality provided by NestedMatch by replicating expected patterns. The NestedMatch class handles with complex macros. Add an unittest to check if its doing the right thing and detect eventual regressions as we improve its code. LLMs are pretty good writing unit tests, as those are just repetitive patterns that are built from the existing code. To speedup writing this one, I used gpt-oss:latest running on my local GPU, feeding it with my class and with replacement patterns from the kernel. I highly modified the generated code, though to ensure that the testset is representative and that all tests pass. $ tools/unittests/nested_match.py Ran 35 tests in 0.001s OK nested_match: TestStructGroup: test_struct_group_01: OK test_struct_group_02: OK test_struct_group_03: OK test_struct_group_04: OK test_struct_group_05: OK test_struct_group_06: OK test_struct_group_07: OK test_struct_group_08: OK test_struct_group_09: OK test_struct_group_10: OK test_struct_group_11: OK test_struct_group_12: OK test_struct_group_13: OK test_struct_group_14: OK test_struct_group_15: OK test_struct_group_16: OK test_struct_group_17: OK test_struct_group_18: OK test_struct_group_19: OK test_struct_group_sub: OK TestSubMacros: test_acquires_multiple: OK test_acquires_nested_paren: OK test_acquires_simple: OK test_mixed_macros: OK test_must_hold: OK test_must_hold_shared: OK test_no_false_positive: OK test_no_macro_remains: OK TestSubReplacement: test_sub_count_parameter: OK test_sub_mixed_placeholders: OK test_sub_multiple_placeholders: OK test_sub_no_placeholder: OK test_sub_single_placeholder: OK test_sub_with_capture: OK test_sub_zero_placeholder: OK Ran 35 tests Signed-off-by: Mauro Carvalho Chehab --- tools/unittests/nested_match.py | 589 ++++++++++++++++++++++++++++++++ 1 file changed, 589 insertions(+) create mode 100755 tools/unittests/nested_match.py diff --git a/tools/unittests/nested_match.py b/tools/unittests/nested_match= .py new file mode 100755 index 000000000000..570e98730b28 --- /dev/null +++ b/tools/unittests/nested_match.py @@ -0,0 +1,589 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright(c) 2026: Mauro Carvalho Chehab . +# +# pylint: disable=3DC0413,R0904 + + +""" +Unit tests for kernel-doc NestedMatch. +""" + +import os +import re +import sys +import unittest + +# Import Python modules + +SRC_DIR =3D os.path.dirname(os.path.realpath(__file__)) +sys.path.insert(0, os.path.join(SRC_DIR, "../lib/python")) + +from kdoc.kdoc_re import NestedMatch +from unittest_helper import run_unittest + +# ------------------------------------------------------------------------= -- +# Verify if struct_group matches are properly handled +# ------------------------------------------------------------------------= -- + + +class TestStructGroup(unittest.TestCase): + """ + Test diferent struct_group patterns. + + Please notice that in this class, there are multiple whitespaces on + some places. That's because it tries to mimic how kernel-doc parser + internally works. + """ + + @classmethod + def setUpClass(cls): + """ + Define a NestedMatch to be used for all tests picking all + struct_group macros. + """ + cls.matcher =3D NestedMatch(r"\bstruct_group[\w\_]*\(") + + def _check_matches(self, line: str, expected_count: int): + """count and validate each match""" + + matches =3D list(self.matcher.search(line)) + self.assertEqual(len(matches), expected_count, + msg=3Df"Expected {expected_count} matches, got {l= en(matches)}") + + for m in matches: + self.assertTrue(m.startswith("struct_group") and "(" in m, + msg=3Df"Match does not start correctly: {m!r}") + self.assertTrue(m.endswith(")"), + msg=3Df"Match does not end correctly: {m!r}") + + def test_struct_group_01(self): + """one struct_group with nested delimiters.""" + line =3D ( + "__be16 id; struct_group(body, __be16 epl_len; u8 lpl_len; u8" + " chk_code; u8 resv1; u8 resv2; u8" + " payload[ETHTOOL_CMIS_CDB_LPL_MAX_PL_LENGTH]; ); u8 *epl;" + ) + self._check_matches(line, 1) + + def test_struct_group_02(self): + """two struct_group_tagged, one per page_pool_params.""" + line =3D ( + "struct_group_tagged(page_pool_params_fast, fast, unsigned int= " + " order; unsigned int pool_size; int nid; struc= t" + " device *dev; struct napi_struct *napi; enum dma_data_direc= tion" + " dma_dir; unsigned int max_len; unsigned int offset; );" + " struct_group_tagged(page_pool_params_slow, slow, struct" + " net_device *netdev; unsigned int queue_idx; unsigned int " + " flags;)" + ) + self._check_matches(line, 2) + + def test_struct_group_03(self): + """two struct_group_tagged, one with nested structs.""" + line =3D ( + "struct_group_tagged(libeth_xskfq_fp, fp, struct xsk_buff_pool= " + " *pool; struct libeth_xdp_buff **fqes; void = " + " *descs; u32 ntu; u32 " + " count; );u32 pending; u32 = " + " thresh; u32 buf_len; int = " + " nid;" + ) + self._check_matches(line, 1) + + def test_struct_group_04(self): + """one struct_group_tagged with many fields.""" + line =3D ( + "struct_group_tagged(libeth_fq_fp, fp, struct page_pool " + " *pp; struct libeth_fqe *fqes; u32 " + " truesize; u32 count; );enum libeth_fqe_t= ype " + " type:2; bool hsplit:1; bool = " + " xdp:1; u32 buf_len; int = " + " nid;" + ) + self._check_matches(line, 1) + + def test_struct_group_05(self): + """long line with a struct_group(priv_flags_fast).""" + line =3D ( + " struct_group(priv_flags_fast, unsigned long " + " priv_flags:32; unsigned long lltx:1; unsigned long= " + " netmem_tx:1; ); const struct net_device_ops *netdev_op= s;" + " const struct header_ops *header_ops; struct netdev_queue " + " *_tx; netdev_features_t gso_partial_features; unsigned= int" + " real_num_tx_queues; unsigned int " + " gso_max_size; unsigned int gso_ipv4_max_size; u16= " + " gso_max_segs; s16 " + " num_tc;unsigned int mtu; unsigned short " + " needed_headroom; struct netdev_tc_txq " + " tc_to_txq[TC_MAX_QUEUE]; #ifdef CONFIG_XPS; struct xps_dev_m= aps " + " *xps_maps[XPS_MAPS_MAX]; #endif; #ifdef CONFIG_NETFILTER_EGR= ESS;" + " struct nf_hook_entries *nf_hooks_egress; #endif; #ifdef" + " CONFIG_NET_XGRESS; struct bpf_mprog_entry *tcx_egress; #end= if;" + " union { struct pcpu_lstats __percpu *lstats; str= uct" + " pcpu_sw_netstats __percpu *tstats; struct pcpu_dstats" + " __percpu *dstats; }; unsigned long sta= te;" + " unsigned int flags; unsigned short " + " hard_header_len; netdev_features_t features; struct" + " inet6_dev *ip6_ptr; struct bpf_prog *xdp_prog; struct" + " list_head ptype_specific; int " + " ifindex; unsigned int real_num_rx_queues; struct" + " netdev_rx_queue *_rx; unsigned int gro_max_size;" + " unsigned int gro_ipv4_max_size; rx_handler_func_t= " + " *rx_handler; void *rx_handler_data; possible_n= et_t" + " nd_net; #ifdef CONFIG_NETPOLL; struct" + " netpoll_info *npinfo; #endif; #ifdef CONFIG_NET_XGRES= S;" + " struct bpf_mprog_entry *tcx_ingress; #endif; char = " + " name[IFNAMSIZ]; struct netdev_name_node *name_node; str= uct" + " dev_ifalias *ifalias;unsigned long mem_end; unsig= ned" + " long mem_start; unsigned long " + " base_addr;struct list_head dev_list; struct list_head= " + " napi_list; struct list_head unreg_list; struct" + " list_head close_list; struct list_head ptype_a= ll;" + " struct { struct list_head upper; struct list_head lower; }" + " adj_list;xdp_features_t xdp_features; const struct" + " xdp_metadata_ops *xdp_metadata_ops; const struct" + " xsk_tx_metadata_ops *xsk_tx_metadata_ops; unsigned short = " + " gflags; unsigned short needed_tailroom;" + " netdev_features_t hw_features; netdev_features_t " + " wanted_features; netdev_features_t vlan_features;" + " netdev_features_t hw_enc_features; netdev_features_t = " + " mpls_features; unsigned int min_mtu; unsigned int= " + " max_mtu; unsigned short type; unsigned char = " + " min_header_len; unsigned char name_assign_typ= e;" + " int group; struct net_device_stats" + " stats;struct net_device_core_stats __percpu *core_stats;atom= ic_t" + " tx_request;" + ) + self._check_matches(line, 1) + + def test_struct_group_06(self): + """struct_group(addrs).""" + line =3D ( + "struct_group(addrs, unsigned char h_dest[ETH_ALEN]; unsigne= d" + " char h_source[ETH_ALEN]; ); __be16 h_vlan_proto;" + " __be16 h_vlan_TCI; __be16 " + " h_vlan_encapsulated_proto;" + ) + self._check_matches(line, 1) + + def test_struct_group_07(self): + """one struct_group(headers).""" + line =3D ( + "union { struct {struct sk_buff *next; struct sk_buff= " + " *prev; union { struct net_device *dev;unsigned lo= ng " + " dev_scratch; }; }; struct rb_node rbnode;st= ruct" + " list_head list; struct llist_node ll_node; };" + " struct sock *sk; union { ktime_t tstamp;= u64" + " skb_mstamp_ns;};char cb[48] ;" + " union { struct { unsigned long _skb_refdst; void = " + " (*destructor)(struct sk_buff *skb); }; struct list_head = " + " tcp_tsorted_anchor; #ifdef CONFIG_NET_SOCK_MSG; unsigned lon= g " + " _sk_redir; #endif; }; #if defined(CONFIG_NF_CONNTRACK= ) ||" + " defined(CONFIG_NF_CONNTRACK_MODULE); unsigned long = " + " _nfct; #endif; unsigned int len, data_len; __u16 = " + " mac_len, hdr_len;__u16 " + " queue_mapping;#ifdef __BIG_ENDIAN_BITFIELD; #define CLONED_M= ASK " + " (1 << 7); #else; #define CLONED_MASK 1; #endif; #defi= ne" + " CLONED_OFFSET offsetof(struct sk_buff," + " __cloned_offset); __u8 cloned:1, nohdr:1= ," + " fclone:2, peeked:1, head_frag:1, pfmemalloc:1," + " pp_recycle:1;#ifdef CONFIG_SKB_EXTENSIONS; __u8 = " + " active_extensions; #endif;struct_group(headers, __u8 = " + " pkt_type:3;__u8 ignore_df:1; __= u8 " + " dst_pending_confirm:1; __u8 = " + " ip_summed:2; __u8 ooo_okay:1; __u8 = " + " tstamp_type:2;#ifdef CONFIG_NET_XGRESS; __u8 = " + " tc_at_ingress:1;__u8 " + " tc_skip_classify:1; #endif; __u8 " + " remcsum_offload:1; __u8 csum_complete_sw:= 1;" + " __u8 csum_level:2; __u8 = " + " inner_protocol_type:1; __u8 l4_hash:1; __= u8 " + " sw_hash:1; #ifdef CONFIG_WIRELESS; __u8 = " + " wifi_acked_valid:1; __u8 " + " wifi_acked:1; #endif; __u8 no_fcs:1;__u8 = " + " encapsulation:1; __u8 " + " encap_hdr_csum:1; __u8 csum_valid:1; #ifd= ef" + " CONFIG_IPV6_NDISC_NODETYPE; __u8 " + " ndisc_nodetype:2; #endif; #if IS_ENABLED(CONFIG_IP_VS); __u8= " + " ipvs_property:1; #endif; #if" + " IS_ENABLED(CONFIG_NETFILTER_XT_TARGET_TRACE) ||" + " IS_ENABLED(CONFIG_NF_TABLES); __u8 " + " nf_trace:1; #endif; #ifdef CONFIG_NET_SWITCHDEV; __u8 = " + " offload_fwd_mark:1; __u8 " + " offload_l3_fwd_mark:1; #endif; __u8 " + " redirected:1; #ifdef CONFIG_NET_REDIRECT; __u8 = " + " from_ingress:1; #endif; #ifdef CONFIG_NETFILTER_SKIP_EGRESS= ;" + " __u8 nf_skip_egress:1; #endif; #ifdef" + " CONFIG_SKB_DECRYPTED; __u8 decrypted:1;" + " #endif; __u8 slow_gro:1; #if" + " IS_ENABLED(CONFIG_IP_SCTP); __u8 " + " csum_not_inet:1; #endif; __u8 unreadable:= 1;" + " #if defined(CONFIG_NET_SCHED) || defined(CONFIG_NET_XGRESS);" + " __u16 tc_index;#endif; u16 = " + " alloc_cpu; union { __wsum csum; struct { __u16 " + " csum_start; __u16 csum_offset; }; }; __u32 = " + " priority; int skb_iif; __u32 = " + " hash; union { u32 vlan_all; struct { __be16 " + " vlan_proto; __u16 vlan_tci; }; }; #if" + " defined(CONFIG_NET_RX_BUSY_POLL) || defined(CONFIG_XPS); uni= on {" + " unsigned int napi_id; unsigned int sender_cpu; }; };" + " #ifdef CONFIG_NETWORK_SECMARK; __u32 secmark; #end= if;" + " union { __u32 mark; __u32 reserved_tailr= oom;" + " }; union { __be16 inner_protocol; __u8 " + " inner_ipproto; }; __u16 " + " inner_transport_header; __u16 " + " inner_network_header; __u16 inner_mac_head= er;" + " __be16 protocol; __u16 " + " transport_header; __u16 network_header; __= u16 " + " mac_header; #ifdef CONFIG_KCOV; u64 = " + " kcov_handle; #endif; );sk_buff_data_t tail;" + " sk_buff_data_t end; unsigned char *head," + " *data; unsigned int truesize; refcount_t = " + " users; #ifdef CONFIG_SKB_EXTENSIONS;struct skb_ext " + " *extensions; #endif;" + ) + self._check_matches(line, 1) + + def test_struct_group_08(self): + """two struct_group(stats).""" + line =3D ( + "enum ethtool_mac_stats_src src; struct_group(stats, u64" + " tx_pause_frames; u64 rx_pause_frames; ); enum" + " ethtool_mac_stats_src src; struct_group(stats, u64" + " undersize_pkts; u64 oversize_pkts; u64 fragments; u64 jabber= s;" + " u64 hist[ETHTOOL_RMON_HIST_MAX]; u64" + " hist_tx[ETHTOOL_RMON_HIST_MAX]; );" + ) + self._check_matches(line, 2) + + def test_struct_group_09(self): + """struct_group(tx_stats).""" + line =3D ( + "struct_group(tx_stats, u64 pkts; u64 onestep_pkts_unconfirmed= ;" + " u64 lost; u64 err; );" + ) + self._check_matches(line, 1) + + def test_struct_group_10(self): + """struct_group(zeroed_on_hw_restart) with a nested struct.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, u16 fw_id; struct { u8" + " allocated:1; u8 stop_full:1; } status; ); struct list_head l= ist;" + " atomic_t tx_request;" + ) + self._check_matches(line, 1) + + def test_struct_group_11(self): + """struct_group(zeroed_on_hw_restart) with many fields.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, unsigned int status; u32" + " uid_status[IWL_MAX_UMAC_SCANS]; u64 start_tsf; bool" + " last_ebs_failed; enum iwl_mld_pass_all_sched_results_states" + " pass_all_sched_res; u8 fw_link_id; struct { u32" + " last_stats_ts_usec; enum iwl_mld_traffic_load status; }" + " traffic_load; );size_t cmd_size; void *cmd; unsigned long" + " last_6ghz_passive_jiffies; unsigned long" + " last_start_time_jiffies; u64 last_mlo_scan_time;" + ) + self._check_matches(line, 1) + + def test_struct_group_12(self): + """struct_group(zeroed_on_hw_restart) with a huge struct.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, struct ieee80211_bss_conf " + " *fw_id_to_bss_conf[IWL_FW_MAX_LINK_ID + 1]; struct ieee80211= _vif" + " *fw_id_to_vif[NUM_MAC_INDEX_DRIVER]; struct ieee80211_txq " + " *fw_id_to_txq[IWL_MAX_TVQM_QUEUES]; u8 used_phy_ids:" + " NUM_PHY_CTX; u8 num_igtks; struct { bool on; u32 ampdu_ref; = bool" + " ampdu_toggle; u8 p80; struct { struct" + " iwl_rx_phy_air_sniffer_ntfy data; u8 valid:1, used:1; } phy;" + " #ifdef CONFIG_IWLWIFI_DEBUGFS; __le16 cur_aid; u8" + " cur_bssid[ETH_ALEN]; bool ptp_time; #endif; } monitor; #ifde= f" + " CONFIG_PM_SLEEP; bool netdetect; #endif; struct ieee80211_vi= f" + " *p2p_device_vif; bool bt_is_active; struct ieee80211_vif" + " *nan_device_vif; ); struct ieee80211_link_sta " + " *fw_id_to_link_sta[IWL_STATION_COUNT_MAX];struct device *dev= ;" + " struct iwl_trans *trans; const struct iwl_rf_cfg *cfg; const" + " struct iwl_fw *fw; struct ieee80211_hw *hw; struct wiphy *wi= phy;" + " struct wiphy_iftype_ext_capab" + " ext_capab[IWL_MLD_EXT_CAPA_NUM_IFTYPES]; u8" + " sta_ext_capab[IWL_MLD_STA_EXT_CAPA_SIZE]; struct iwl_nvm_dat= a" + " *nvm_data; struct iwl_fw_runtime fwrt; struct dentry" + " *debugfs_dir; struct iwl_notif_wait_data notif_wait; struct" + " list_head async_handlers_list; spinlock_t async_handlers_loc= k;" + " struct wiphy_work async_handlers_wk; struct wiphy_delayed_wo= rk" + " ct_kill_exit_wk; struct { u32 running:1, do_not_dump_once:1," + " #ifdef CONFIG_PM_SLEEP; in_d3:1, resuming:1, #endif;" + " in_hw_restart:1; } fw_status; struct { u32 hw:1, ct:1; }" + " radio_kill; u32 power_budget_mw; struct mac_address" + " addresses[IWL_MLD_MAX_ADDRESSES]; struct iwl_mld_scan scan;" + " struct iwl_mld_survey *channel_survey; #ifdef CONFIG_PM_SLEE= P;" + " struct wiphy_wowlan_support wowlan; u32 debug_max_sleep; #en= dif;" + " #ifdef CONFIG_IWLWIFI_LEDS; struct led_classdev led; #endif;" + " enum iwl_mcc_source mcc_src; bool bios_enable_puncturing; st= ruct" + " iwl_mld_baid_data *fw_id_to_ba[IWL_MAX_BAID]; u8" + " num_rx_ba_sessions; struct iwl_mld_rx_queues_sync rxq_sync;" + " struct list_head txqs_to_add; struct wiphy_work add_txqs_wk;" + " spinlock_t add_txqs_lock; u8 *error_recovery_buf; struct" + " iwl_mcast_filter_cmd *mcast_filter_cmd; u8 mgmt_tx_ant; u8" + " set_tx_ant; u8 set_rx_ant; bool fw_rates_ver_3; struct" + " iwl_mld_low_latency low_latency; bool ibss_manager; #ifdef" + " CONFIG_THERMAL; struct thermal_zone_device *tzone; struct" + " iwl_mld_cooling_device cooling_dev; #endif; struct ptp_data" + " ptp_data; struct iwl_mld_time_sync_data *time_sync; struct" + " ftm_initiator_data ftm_initiator;" + ) + self._check_matches(line, 1) + + def test_struct_group_13(self): + """struct_group(zeroed_on_not_authorized).""" + line =3D ( + "struct_group(zeroed_on_not_authorized, u8 primary; u8" + " selected_primary; u16 selected_links; enum iwl_mld_emlsr_blo= cked" + " blocked_reasons; enum iwl_mld_emlsr_exit last_exit_reason;" + " unsigned long last_exit_ts; u8 exit_repeat_count; unsigned l= ong" + " last_entry_ts; ); struct wiphy_work unblock_tpt_wk; struct" + " wiphy_delayed_work check_tpt_wk; struct wiphy_delayed_work" + " prevent_done_wk; struct wiphy_delayed_work tmp_non_bss_done_= wk;" + ) + self._check_matches(line, 1) + + def test_struct_group_14(self): + """struct_group(zeroed_on_hw_restart) with nested struct.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, u8 fw_id; struct" + " iwl_mld_session_protect session_protect; struct ieee80211_st= a" + " *ap_sta; bool authorized; u8 num_associated_stas; bool" + " ap_ibss_active; enum iwl_mld_cca_40mhz_wa_status" + " cca_40mhz_workaround; #ifdef CONFIG_IWLWIFI_DEBUGFS; bool" + " beacon_inject_active; #endif; u8 low_latency_causes; bool" + " ps_disabled; time64_t last_link_activation_time; );struct" + " iwl_mld *mld; struct iwl_mld_link deflink; struct iwl_mld_li= nk " + " *link[IEEE80211_MLD_MAX_NUM_LINKS]; struct iwl_mld_emlsr eml= sr;" + " #ifdef CONFIG_PM_SLEEP; struct iwl_mld_wowlan_data wowlan_da= ta;" + " #endif; #ifdef CONFIG_IWLWIFI_DEBUGFS; bool use_ps_poll; boo= l" + " disable_bf; struct dentry *dbgfs_slink; #endif; enum" + " iwl_roc_activity roc_activity; struct iwl_mld_int_sta aux_st= a;" + " struct wiphy_delayed_work mlo_scan_start_wk;" + ) + self._check_matches(line, 1) + + def test_struct_group_15(self): + """struct_group(zeroed_on_hw_restart) with small struct.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, u32 last_rate_n_flags; boo= l" + " in_fw; s8 signal_avg; );struct rcu_head rcu_head; u32 fw_id;" + ) + self._check_matches(line, 1) + + def test_struct_group_16(self): + """struct_group(zeroed_on_hw_restart) with many enums.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, enum ieee80211_sta_state" + " sta_state; enum iwl_fw_sta_type sta_type; );struct iwl_mld *= mld;" + " struct ieee80211_vif *vif; struct iwl_mld_rxq_dup_data" + " *dup_data; u8 tid_to_baid[IWL_MAX_TID_COUNT]; u8 data_tx_ant= ;" + " struct iwl_mld_link_sta deflink; struct iwl_mld_link_sta " + " *link[IEEE80211_MLD_MAX_NUM_LINKS]; struct iwl_mld_ptk_pn " + " *ptk_pn[IWL_NUM_DEFAULT_KEYS]; struct iwl_mld_per_q_mpdu_cou= nter" + " *mpdu_counters;" + ) + self._check_matches(line, 1) + + def test_struct_group_17(self): + """struct_group(zeroed_on_hw_restart) with channel data.""" + line =3D ( + "struct_group(zeroed_on_hw_restart, u8 fw_id; struct" + " cfg80211_chan_def chandef; );u32 channel_load_by_us; u32" + " avg_channel_load_not_by_us; struct iwl_mld *mld;" + ) + self._check_matches(line, 1) + + def test_struct_group_18(self): + """mixture of struct_group and struct rcu_head.""" + line =3D ( + "struct rcu_head rcu_head;struct_group(zeroed_on_hw_restart, u= 8" + " fw_id; bool active; struct ieee80211_tx_queue_params" + " queue_params[IEEE80211_NUM_ACS]; struct ieee80211_chanctx_co= nf " + " *chan_ctx; bool he_ru_2mhz_block; struct ieee80211_key_conf" + " *igtk; struct ieee80211_key_conf *bigtks[2]; );struct" + " iwl_mld_int_sta bcast_sta; struct iwl_mld_int_sta mcast_sta;" + " struct iwl_mld_int_sta mon_sta;struct ieee80211_key_conf" + " *ap_early_keys[6]; u32 average_beacon_energy; bool" + " silent_deactivation; struct iwl_probe_resp_data " + " *probe_resp_data;" + ) + self._check_matches(line, 1) + + def test_struct_group_19(self): + """x(ice_health_tx_hang_buf).""" + line =3D ( + "struct devlink_health_reporter *fw; struct" + " devlink_health_reporter *mdd; struct devlink_health_reporter" + " *port; struct devlink_health_reporter *tx_hang;" + " struct_group_tagged(ice_health_tx_hang_buf, tx_hang_buf, str= uct" + " ice_tx_ring *tx_ring; u32 head; u32 intr; u16 vsi_num; ); st= ruct" + " ice_aqc_health_status_elem fw_status; struct" + " ice_aqc_health_status_elem port_status;" + ) + self._check_matches(line, 1) + + def test_struct_group_sub(self): + """Replace struct_group body with a placeholder.""" + line =3D "foo bar struct_group(my, a(b{c}), d); qux;" + + result =3D NestedMatch(r"\bstruct_group\(").sub("REPLACED", line) + expected =3D "foo bar REPLACED qux;" + + self.assertEqual(result, expected) + + +class TestSubMacros(unittest.TestCase): + """ + Test macros that will be dropped. + """ + + def test_acquires_simple(self): + """Simple replacement test with __acquires""" + line =3D "__acquires(ctx) foo();" + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + + self.assertNotIn("__acquires(", result) + self.assertIn("foo();", result) + + def test_acquires_multiple(self): + """Multiple __acquires""" + line =3D "__acquires(ctx) __acquires(other) bar();" + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + + self.assertNotIn("__acquires(", result) + self.assertEqual(result.count("REPLACED"), 2) + + def test_acquires_nested_paren(self): + """__acquires with nested pattern""" + line =3D "__acquires((ctx1, ctx2)) baz();" + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + + self.assertNotIn("__acquires(", result) + self.assertIn("baz();", result) + + def test_must_hold(self): + """__must_hold with a pointer""" + line =3D "__must_hold(&lock) do_something();" + result =3D NestedMatch(r"__must_hold\s*\(").sub("REPLACED", line) + + self.assertNotIn("__must_hold(", result) + self.assertIn("do_something();", result) + + def test_must_hold_shared(self): + """__must_hold with an upercase defined value""" + line =3D "__must_hold_shared(RCU) other();" + result =3D NestedMatch(r"__must_hold_shared\s*\(").sub("REPLACED",= line) + + self.assertNotIn("__must_hold_shared(", result) + self.assertIn("other();", result) + + def test_no_false_positive(self): + """ + Ensure that unrelated text containing similar patterns is preserved + """ + line =3D "call__acquires(foo); // should stay intact" + result =3D NestedMatch(r"\b__acquires\s*\(").sub("REPLACED", line) + + self.assertEqual(result, line) + + def test_mixed_macros(self): + """Add a mix of macros""" + line =3D "__acquires(ctx) __releases(ctx) __must_hold(&lock) foo()= ;" + + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + result =3D NestedMatch(r"__releases\s*\(").sub("REPLACED", result) + result =3D NestedMatch(r"__must_hold\s*\(").sub("REPLACED", result) + + self.assertNotIn("__acquires(", result) + self.assertNotIn("__releases(", result) + self.assertNotIn("__must_hold(", result) + + self.assertIn("foo();", result) + + def test_no_macro_remains(self): + """Ensures that unmatched macros are untouched""" + line =3D "do_something_else();" + result =3D NestedMatch(r"__acquires\s*\(").sub("REPLACED", line) + + self.assertEqual(result, line) + + +class TestSubReplacement(unittest.TestCase): + """Test argument replacements""" + + @classmethod + def setUpClass(cls): + """Define a NestedMatch to be used for all tests""" + cls.matcher =3D NestedMatch(re.compile(r"__acquires\s*\(")) + + def test_sub_with_capture(self): + """Test all arguments replacement with a single arg""" + line =3D "__acquires(&ctx) foo();" + + result =3D self.matcher.sub(r"ACQUIRED(\0)", line) + + self.assertIn("ACQUIRED(&ctx)", result) + self.assertIn("foo();", result) + + def test_sub_zero_placeholder(self): + """Test all arguments replacement with a multiple args""" + line =3D "__acquires(arg1, arg2) bar();" + + result =3D self.matcher.sub(r"REPLACED(\0)", line) + + self.assertIn("bar();", result) + self.assertIn("REPLACED(arg1, arg2)", result) + + def test_sub_single_placeholder(self): + """Single replacement rule for \1""" + line =3D "__acquires(ctx) foo();" + result =3D self.matcher.sub(r"ACQUIRED(\1)", line) + + self.assertIn("foo();", result) + self.assertIn("ACQUIRED(ctx)", result) + + def test_sub_multiple_placeholders(self): + """Replacement rule for both \1 and \2""" + line =3D "__acquires(arg1, arg2) bar();" + result =3D self.matcher.sub(r"REPLACE(\1, \2)", line) + + self.assertIn("bar();", result) + self.assertIn("REPLACE(arg1, arg2)", result) + + def test_sub_mixed_placeholders(self): + """Replacement rule for \0, \1 and additional text""" + line =3D "__acquires(foo, bar) baz();" + result =3D self.matcher.sub(r"START(\0) END(\1)", line) + + self.assertIn("baz();", result) + self.assertIn("START(foo, bar) END(foo)", result) + + def test_sub_no_placeholder(self): + """Replacement without placeholders""" + line =3D "__acquires(arg) foo();" + result =3D self.matcher.sub(r"NO_BACKREFS()", line) + + self.assertIn("foo();", result) + self.assertIn("NO_BACKREFS()", result) + + def test_sub_count_parameter(self): + """Verify that the algorithm stops after the requested count""" + line =3D "__acquires(a1) x(); __acquires(a2) y();" + result =3D self.matcher.sub(r"ONLY_FIRST(\1)", line, count=3D1) + + self.assertIn("ONLY_FIRST(a1) x();", result) + self.assertIn("__acquires(a2) y();", result) + + +# ---------------------------------------------------------------------- +# Run all tests +# ---------------------------------------------------------------------- +if __name__ =3D=3D "__main__": + run_unittest(__file__) --=20 2.52.0 From nobody Wed Feb 11 02:24:22 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 2E6B0378830; Wed, 28 Jan 2026 16:50:38 +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=1769619038; cv=none; b=sWgtO++odJuGDHi5WZF5+XbrApxXUDJXsGzCuaiJN4YmsnmUNAs6E902/CAIJhEDZ8H9/ETBmFTWEsT8ahuETV8AkCgmx69dv1osrj6UK6ybPVPX3SYzXQGmAKxI2YXGUC/xQ5NGlM4OFsHKFCTQfS6pE2oZ7nV6y44Q/HAYjHk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619038; c=relaxed/simple; bh=xPgXK1Bxhql6KwBQMghZiM8porm1utQ6AVnpiugaqXI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=GLMGZQuYFL+a1zDwDkpqANqcjxeZQVBS2iR736h88CqjsGLWEH+2FfmDscfyP7OegUxmtI2eC3/CPhI6xkplAR+A4rhuuqAfodWoYEt3ox3VC1YDYz7x24t/c0HKLjbH62C/oXIIR4tB7vhN7EWEhzUYmF1Qwb0yur4ggtcB2MA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=L52Is0d2; 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="L52Is0d2" Received: by smtp.kernel.org (Postfix) with ESMTPSA id EF896C4CEF7; Wed, 28 Jan 2026 16:50:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619038; bh=xPgXK1Bxhql6KwBQMghZiM8porm1utQ6AVnpiugaqXI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=L52Is0d2Mam9VJ+4YyKHw1zLjYczDjF+baeNR4vHB26sFkhUBDLbAVrQFv2uTDSKC d7cLGmgpmI93G/ZRxWuZS8P4LzgHpLLntNDVJTs163AvSVDSS326iDw8yHfbJzXAUs 7akuYBSCS1QjtWefJUVP8iWzgl7unab3zdzhgTO5+ygwLEdzTljtWwYIfnlwAqxRUQ ZaHiv9HLvtufnVmn1+/piCFM3ZQogA3HNU/VunJZQKYtI/bUm4ljfWDkxUfexL0VRA LSdCAMa0h/oR+dWNMSlAFb00nE5+7b24OayJ0TKOejbCXpe0ulDsf0383a+/LA+Xed JMZ2p1xI9Zk9g== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kW-0000000DBB4-0bdW; Wed, 28 Jan 2026 17:50:36 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Shuah Khan , Stephen Rothwell Subject: [PATCH v2 23/25] tools/lib/python/unittest_helper.py Date: Wed, 28 Jan 2026 17:50:21 +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 Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/unittest_helper.py | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/tools/lib/python/unittest_helper.py b/tools/lib/python/unittes= t_helper.py index e438472fa704..3cf1075b1de4 100755 --- a/tools/lib/python/unittest_helper.py +++ b/tools/lib/python/unittest_helper.py @@ -8,21 +8,7 @@ Helper class to better display unittest results. =20 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) - ? ^^^^^ - ... +executed test. =20 It also allows filtering what tests will be executed via ``-k`` parameter. =20 --=20 2.52.0 From nobody Wed Feb 11 02:24:22 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 AA286378D9B; Wed, 28 Jan 2026 16:50:38 +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=1769619038; cv=none; b=Tsh+Y4XjRevfJ4Iyi5XhYpspazeEwTgTo4neL5rYzTqlVD6bd3mAT6vBLOppW5KoTXZC1QOJAKXotYfVGAqznH/MuHdGD3fTnF1xXz/5J3JMBEsps5tTyG538+q1QQYnyNlhky4FSiIU82T4zd11NbX3bOJCp1hNk/sLL9i5LL0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619038; c=relaxed/simple; bh=Vgz8udadx0cwepC/wsp/hEk+Bl4FBDA/00MijiNSly0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=cOTjCONen+6Zmr/afUQ6bgcA2GmeTjpCd0wcrvsSdFEVtb7cRFuhdZICc8/Dzw48vfbv9FLhnJusxwYansrdAPHqEgrnV4S+rl0diYUKiXaTG2NazO4FBMI9WuhAN2Depsahqb12Bd+jSB3v4elXeCSCtZD++deauSpqbimSH5E= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=gtlM6Spw; 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="gtlM6Spw" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8C9CBC4CEF1; Wed, 28 Jan 2026 16:50:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619038; bh=Vgz8udadx0cwepC/wsp/hEk+Bl4FBDA/00MijiNSly0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gtlM6Spw+83hTzIkZLcSXE1dgusRIqZfidCRPGyq3PaZDJQa9WIT71sHFy+VlbnoL J4Fgq/6C7J8i79jMSLjGmMv7out8vV4lf4HpORi42gCVNb3/JbSYjWWYtPTWBIQiV0 iDwmn6cWJaO52FgVTMMcCp/RQtWpl+VZLSPgfOZ6l+TqJ/OqnSUcMGuQDTgxJ45ipJ zSud7R5toJkmE0WFFC4bzLsZHd3/HNJYXWDNQdqtlBhfUlL/qV+LIJDALRwo5K2Rl/ KlEKgSynkBSfO5we5yqoGSbdMl2MxU/QHyLytcno5aeh5/pdj6wR16EruEZUauV4Cs vPP8jya4LPsTg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kW-0000000DBCG-1tTl; Wed, 28 Jan 2026 17:50:36 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 24/25] docs: kdoc_parser: better handle struct_group macros Date: Wed, 28 Jan 2026 17:50:22 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Instead of converting them on two steps, implement a single logic to parse them using the new sub functionality of NestedMatch.sub(). Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Aleksandr Loktionov --- tools/lib/python/kdoc/kdoc_parser.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index 3a5614106af7..d2eb93f9d489 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -124,10 +124,11 @@ struct_xforms =3D [ # matched. So, the implementation to drop STRUCT_GROUP() will be # handled in separate. # - (KernRe(r'\bstruct_group\s*\(([^,]*,)', re.S), r'STRUCT_GROUP('), - (KernRe(r'\bstruct_group_attr\s*\(([^,]*,){2}', re.S), r'STRUCT_GROUP(= '), - (KernRe(r'\bstruct_group_tagged\s*\(([^,]*),([^,]*),', re.S), r'struct= \1 \2; STRUCT_GROUP('), - (KernRe(r'\b__struct_group\s*\(([^,]*,){3}', re.S), r'STRUCT_GROUP('), + (NestedMatch(r'\bstruct_group\s*\('), r'\2'), + (NestedMatch(r'\bstruct_group_attr\s*\('), r'\3'), + (NestedMatch(r'\bstruct_group_tagged\s*\('), r'struct \1 { \3 } \2;'), + (NestedMatch(r'\b__struct_group\s*\('), r'\4'), + # # Replace macros # @@ -153,7 +154,6 @@ struct_xforms =3D [ (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', r= e.S), r'dma_addr_t \1'), (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re= .S), r'__u32 \1'), (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1; u64= \1_array[VIRTIO_FEATURES_U64S]; }'), - (NestedMatch(r'\bSTRUCT_GROUP\('), r'\0'), ] =20 # --=20 2.52.0 From nobody Wed Feb 11 02:24:22 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 B31113793A7; Wed, 28 Jan 2026 16:50:38 +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=1769619038; cv=none; b=Cfytg16PfFkyr91HmUUjvWKPoZu9YrwEL8lFri53F4IzH42Sgee5yx5m1osFXa6KJk8FfoJxDsDIwz2qKZ/gmd5SFO94pEuRXIis14AInJQkg7l0S45klSMGM87bWmljVP+LZNrI0Kxa1LczsFztQ+XdFWQj5eah1wZDs+vgPhs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769619038; c=relaxed/simple; bh=yKLcYi21z0S4G3m+JtOZZ58rdI04u1dgDTVjrPTBONM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=tSp4vV7nMjH9jXVXE+sffc6NqyUBQSkI+LsxecXpm6D4dlVjMJeiVaBdNmlpbeIyB6Mu4guCu+EfcXDc4vnpNy3Wu8PSkm92tAvdVfWEznx9zle2FX+QqKodm6UKgX4etXYhvsIAXLU+s/zrjaPzExNkVu6BYBDr1IxN1dfTbmM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=QNYwL1Ll; 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="QNYwL1Ll" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 94F5AC116C6; Wed, 28 Jan 2026 16:50:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1769619038; bh=yKLcYi21z0S4G3m+JtOZZ58rdI04u1dgDTVjrPTBONM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=QNYwL1LloL0tgc/bNbJ4eTY7SP6VRNYxS21BwoJeOsGGSveE04ClXL0HOZ/+PDRnX FCf2Eg4BOqbx+rQ/c7VcgGslBcOlePMq7GI5oSPnfg7OgxUfFJvOVZWnEaS/vZ2Xb0 iA8YYy7c8KI8IH9FHszPoQ2+0hoUZP4hE4+gn69yB//YUgiCiYlRtiPZZ4h+CZ9CSs 8IUbbvq8LNjEwpFzj63GeIm7toBEilk6XFGTLdms7NmdMlBF5Zny79vYw4NoWikm9A jIAFIA34uV+sF9pHgazcC7oJm1x7EnJtAah71fcCrzD4MFumRQFoho9+5bzUGpNS92 5NCEx/7eluGJQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1vl8kW-0000000DBDS-33rZ; Wed, 28 Jan 2026 17:50:36 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , bpf@vger.kernel.org, intel-wired-lan@lists.osuosl.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Peter Zijlstra , Randy Dunlap , Stephen Rothwell Subject: [PATCH v2 25/25] docs: kdoc_re: fix a parse bug on struct page_pool_params Date: Wed, 28 Jan 2026 17:50:23 +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 f49a568b9155..8d4cfdf8f479 100644 --- a/tools/lib/python/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -206,6 +206,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() @@ -255,6 +258,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