From nobody Fri Apr 3 20:51:58 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 F0C2438644F; Mon, 23 Mar 2026 09:10:58 +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=1774257059; cv=none; b=gW1YmF27QG2fYiw21k5xHFV9M9vcg/ngiCwSWqPryBmbmojg3GgETQsRmVU11OZeIVSOXSLyzkJN9XbLSjdPUrJRuhuUpBpcBZhiEUl6g6TDvcJbL6yjBKMvkps4l1FAACIUeF0d1tL/EaDspWLY6RLtVfgOBBKmaPBkWHd8/Ko= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774257059; c=relaxed/simple; bh=aqYdN+DcUv3ujKrgqqFAwZYM7QbeYhyVHwsYgAW9BR0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=DA6z9gCKmvG2sJwbdq/HbJvitw4dwJAey3R+S8X9ZkXH48sYMUbmNwAwHPIDivo69NTwD9htNavYTn2eu+MBGs8rS0TgL0aIjKfDLpxuqHr+Va/XF2YHq8v3XtBtE4v5aVMW3GBztPE+5V5mJxJurRftke+rUATzEfkCR92yKXs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Lw6Jvsy9; 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="Lw6Jvsy9" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C93DEC2BCB0; Mon, 23 Mar 2026 09:10:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1774257058; bh=aqYdN+DcUv3ujKrgqqFAwZYM7QbeYhyVHwsYgAW9BR0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Lw6Jvsy9BhRr9YbH1YGe78gBsCnA6tGi5cWGpAMuSUMu0U4n2ggsFd+0bws3m8FDR ve8XzuDjZnML8yu6YdbRSF9SE3w5QgG8JCKcIpT73oFNBbBXE3RFPTXibkZGkVHN7Z 59uY9FN+anYgGjOCzWpDnK8tv4xV2uLvg5Yericx06TaEGJJy44qJaQoygNIKbRNB6 2lytEY6cR49KZMdZXGJDHpx5gZBE4qmjjGjRS15ZcCwjfrX+xBxO/q5dKimKxS+8Op AMXbP3YPcYFIV1iCe5zYruU0a+36cGJVcb1jgLJ6xIlw4Dx6lzr532wBGGZG0W7Zzi PbIthqgVZsinA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1w4bJI-00000002yWI-1bpu; Mon, 23 Mar 2026 10:10:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 01/10] MAINTAINERS: update documentation scripts to add unittests Date: Mon, 23 Mar 2026 10:10:44 +0100 Message-ID: <6be396b8423372dd006484351ca2dbc54220587e.1774256269.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.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 Ensure that we'll receive e-mails for attempts to touch tools/unittests. While here, place entries alphabetically sorted. Signed-off-by: Mauro Carvalho Chehab --- MAINTAINERS | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/MAINTAINERS b/MAINTAINERS index c05a72245049..f0b106a4dd96 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7679,8 +7679,9 @@ M: Mauro Carvalho Chehab L: linux-doc@vger.kernel.org S: Maintained F: Documentation/sphinx/ -F: tools/lib/python/* F: tools/docs/ +F: tools/lib/python/* +F: tools/unittests/* =20 DOCUMENTATION/ITALIAN M: Federico Vaga --=20 2.53.0 From nobody Fri Apr 3 20:51:58 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 20974386458; Mon, 23 Mar 2026 09:10:59 +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=1774257059; cv=none; b=sLRtIgtpAFdV1aXDWhE4KzB2gpD7p6WzcbnoMK7Kl1ibOQ1FOT1E2gW9QJUMdhy9UWGi4UgSKid6R/sIVG777fUQ/vwvuy/g/U2SYvK+CwZ7bjxIlUsirtdM09CkL6ckvfOxDikXshvPZsessO7+0BVKCxPZRNXbUYnkbEe9eMw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774257059; c=relaxed/simple; bh=9bP3dZmN9dqpLzA2P9uYLroVbRJTwYSVc6XXaOpsBAY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=paL5HxVpmOo2rUY+9ZzECcT9JGqlWxZNkfTq4aNN6XvTK28EOVrZKz66/XN7z5l5AXg1BZcOkaojG8qNz61gKp0No0ZsbW5jRJ3tpuLEiBGRvFKK/CDDCydRDPbtUAYq22B2bP51Q6LY9XBdspiUgbB7pPSiomS3ZR67+KRQ8b8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=swUYgibz; 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="swUYgibz" Received: by smtp.kernel.org (Postfix) with ESMTPSA id CB981C2BCB4; Mon, 23 Mar 2026 09:10:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1774257058; bh=9bP3dZmN9dqpLzA2P9uYLroVbRJTwYSVc6XXaOpsBAY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=swUYgibzFJdQN8iDOu5XIB9/VQqqZyTluwz/hNGv0wKnXiJswJRt39TEN1+M35w22 PURQSoT7ESF2W7yDkFTnPNHGXtHwplQTdNWHEZQtKJTCFVXvBw3kmCpLgTwbzmnAY6 K0ZWV/EoFQKE5tCJJXnxNBxsZQxFgk3pEBzbT4OIx2ptdvckTwgG1p4JvI6+Wmwm+4 5mlltT9RjT9WWs0NsUwL9BQVTAFQCRBVdH+E3qPbZAVvf92wkIXMqjPCQtEAcLcruU Hr/poTyBwo76zlpfgXhdalQwfrUqoEGMDFb6sM9RpakIXwOY3izzJnLhGg+vX/7aoM vUSqCV5Puv5Qw== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1w4bJI-00000002yWM-1ipo; Mon, 23 Mar 2026 10:10:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH 02/10] unittests: test_kdoc_parser: add command line arg to read a YAML file Date: Mon, 23 Mar 2026 10:10:45 +0100 Message-ID: <1d1a56de012c43756f9ca87aa9bf6c285674f113.1774256269.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.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 test_kdoc_parser.py already supports loading dynamic tests when running unit tests. Add support to read from a different file. This is useful for: - regression tests before/afer some changes; - preparing new unit tests; - test a different yaml before adding its contents at tools/unittests/kdoc-test.yaml. It should be noticed that passing an argument to a unit test is not too trivial, as unittest core will load itself the runner with a separate environment. The best (only?) way to do it is by setting the system environment. This way, when the class is called by the unit test loader, it can pick the var from the environment without relying on a global variable. The unittest_helper has already provision for it, so let's use its support. Signed-off-by: Mauro Carvalho Chehab --- tools/unittests/test_kdoc_parser.py | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdo= c_parser.py index 723dd8c7f4f3..f2250ef192ce 100755 --- a/tools/unittests/test_kdoc_parser.py +++ b/tools/unittests/test_kdoc_parser.py @@ -30,7 +30,7 @@ from kdoc.kdoc_output import RestFormat, ManFormat =20 from kdoc.xforms_lists import CTransforms =20 -from unittest_helper import run_unittest +from unittest_helper import TestUnits =20 =20 # @@ -38,6 +38,10 @@ from unittest_helper import run_unittest # TEST_FILE =3D os.path.join(SRC_DIR, "kdoc-test.yaml") =20 +env =3D { + "yaml_file": TEST_FILE +} + # # Ancillary logic to clean whitespaces # @@ -470,7 +474,9 @@ class KernelDocDynamicTests(): optional ones. """ =20 - with open(TEST_FILE, encoding=3D"utf-8") as fp: + test_file =3D os.environ.get("yaml_file", TEST_FILE) + + with open(test_file, encoding=3D"utf-8") as fp: testset =3D yaml.safe_load(fp) =20 tests =3D testset["tests"] @@ -531,4 +537,15 @@ KernelDocDynamicTests.create_tests() # Run all tests # if __name__ =3D=3D "__main__": - run_unittest(__file__) + runner =3D TestUnits() + parser =3D runner.parse_args() + parser.add_argument("-y", "--yaml-file", "--yaml", + help=3D'Name of the yaml file to load') + + args =3D parser.parse_args() + + if args.yaml_file: + env["yaml_file"] =3D os.path.expanduser(args.yaml_file) + + # Run tests with customized arguments + runner.run(__file__, parser=3Dparser, args=3Dargs, env=3Denv) --=20 2.53.0 From nobody Fri Apr 3 20:51:58 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 223D538645D; Mon, 23 Mar 2026 09:10:59 +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=1774257059; cv=none; b=lTuJAiTxKYvdWhV36cHz779uQ7dCqAEi8YOy/q1VMfNQeWy7P/KsrOt5jadlkIAr6zR7e9Kd18vJyibl/9XBMqRzXEzAYQ42YHAXGgtC2w3CFe3j12c+IcPYrD5je14nf7EHK+iFD2xbMM/6lJRMMUYPtqcBr8s4798eYD7vWHg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774257059; c=relaxed/simple; bh=sE2ufwJ3Rjh+ZZYr6fE4OW6hNDnKOem4oD9XoiJcCV4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=liVQGwhLVYQwJh9eRImDPRIgagy30zsBj1VdI5GXdnkxylMwTmldJQ1iS6Uph5VGgQjfELBEmxXKnoAen4GBWOE8rhXKP+MBW0j2+cNHnm8WV+MswUYmudXh3UL+3UPx+od1BpZ8X18tgB6Bxg/LBFjNAg5rJ+20zuFHQVnClb8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=LSc3LCPD; 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="LSc3LCPD" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D250EC4AF0B; Mon, 23 Mar 2026 09:10:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1774257058; bh=sE2ufwJ3Rjh+ZZYr6fE4OW6hNDnKOem4oD9XoiJcCV4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=LSc3LCPD3bWS00aQpjhk9KQ+0TmI8JFotory9D2S2RKWnH+2KWxklnwXbk3n7BWuX IqwDnC1Am8kiaFrYsccrHHa4yfqY+vBiFUiVGn8zHC09hwXad7EyBV0kBxsxHnu8lE p0Gu7ifW6SyD6Ui1kyHadGLv6ZG+RiGygJxjvBH+h/dJwZq8zqTsA9G5lYsif3tp+0 2Hlc08rToxLnzzx/QrzagBA5FF09Zhc8GGej/iY/McMG4FwVmZBA+PzBW/5pUzXiBB sQnWCn7Y9/TjRjr0n++q76iHdFHAm8wUYtwr6XTKxUsAEfDE0VBeEbUrLhkZ2rVzVz kZw/KCFSMY2iQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1w4bJI-00000002yWQ-1pgH; Mon, 23 Mar 2026 10:10:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH 03/10] docs: tools: include kdoc_yaml_file at documentation Date: Mon, 23 Mar 2026 10:10:46 +0100 Message-ID: <32b86abe7acee2dd4f73a35836ec94e8690f04cd.1774256269.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.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 autodoc entry for the new kdoc_yaml_file module. Signed-off-by: Mauro Carvalho Chehab --- Documentation/tools/kdoc_ancillary.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/tools/kdoc_ancillary.rst b/Documentation/tools/k= doc_ancillary.rst index 85f3806a431a..249753744d11 100644 --- a/Documentation/tools/kdoc_ancillary.rst +++ b/Documentation/tools/kdoc_ancillary.rst @@ -53,3 +53,11 @@ Python version ancillary methods :members: :show-inheritance: :undoc-members: + +Write output on YAML file +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +.. automodule:: lib.python.kdoc.kdoc_yaml_file + :members: + :show-inheritance: + :undoc-members: --=20 2.53.0 From nobody Fri Apr 3 20:51:58 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 19683386453; Mon, 23 Mar 2026 09:10:58 +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=1774257059; cv=none; b=cLCgMZpJPMxLi6VvanM0fyJcQgwg+K7ZZsaRO/GqCqw0PpKDkx7eLuZTj6EzwuYFplnEZMDuJIIzqUgAEZICRQnRJ6e74Z6nDhAABJJBUNxqHhhFStiG4eaoXzn7kZZn+d5GVQye43MEWQDd4yRs0NIaSlaPzWbkUIpAnC6OBNY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774257059; c=relaxed/simple; bh=fPzInczANAdOGjNACOlImNH9I8DEnTQnoNy6KxDMv84=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=CL903bWcEqOPFeY1JALADuWXzSrvdUkC1TnD8n4ra15u5D89Q9VYG1MEIvX6LqxfEdv1I39S1qTU6gmSkKtpc1l3DXN9sls6UOyQHSexRwUqNruV6eEiyCczekYABBD01bW38yIt9fChq2+NiIkmStSdpgMHz0V9n+uV8Gi9dqQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=WcxXn9Kb; 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="WcxXn9Kb" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C3572C2BC9E; Mon, 23 Mar 2026 09:10:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1774257058; bh=fPzInczANAdOGjNACOlImNH9I8DEnTQnoNy6KxDMv84=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=WcxXn9KbyrozgA4LcNrurgvB0aXFzvx395cXPq97WNBvy5kvoTHwYsGDdzvu/aV+1 P5Biji5gFqwd0K7A03F/DOtK1BHPNyurf3u1Xg5IsGtwTNoa8FOtlKd4uspevalYnF ZX8ka64VQTklRi2s9ZOD6/JTwagU6Q1LS43rz2qCUFU4CdQPkX9pY/Pf5+i00ZaFCa DaJxJcoqJMcYEfwZN/jVNkXY+H/mje6uklt7cA99xPW9i+UxMBvwwixlQRadfKG4AZ tR80hXq/5jszy9DZ2dNIewvfHLkRUyHozirLX14b9Eomv8YR4LFX9DmmysbnVbAXqX aU6KSHPmmCYXg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1w4bJI-00000002yWU-1wWB; Mon, 23 Mar 2026 10:10:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 04/10] docs: kdoc_yaml_file: add a representer to make strings look nicer Date: Mon, 23 Mar 2026 10:10:47 +0100 Message-ID: <422041a8b49b2609de5749092fe074b7948c32a6.1774256269.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.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 strings representation is not ok, currently. Add a helper function to improve it, and drop blank lines at beginning and at the end of the dumps Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_yaml_file.py | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_yaml_file.py b/tools/lib/python/kdo= c/kdoc_yaml_file.py index db131503c3f6..18737abb1176 100644 --- a/tools/lib/python/kdoc/kdoc_yaml_file.py +++ b/tools/lib/python/kdoc/kdoc_yaml_file.py @@ -126,7 +126,7 @@ class KDocTestFile(): else: key =3D "rst" =20 - expected_dict[key]=3D out_style.output_symbols(fname, [arg= ]) + expected_dict[key]=3D out_style.output_symbols(fname, [arg= ]).strip() =20 name =3D f"{base_name}_{i:03d}" =20 @@ -148,8 +148,20 @@ class KDocTestFile(): """ import yaml =20 + # Helper function to better handle multilines + def str_presenter(dumper, data): + if "\n" in data: + return dumper.represent_scalar("tag:yaml.org,2002:str", da= ta, style=3D"|") + + return dumper.represent_scalar("tag:yaml.org,2002:str", data) + + # Register the representer + yaml.add_representer(str, str_presenter) + data =3D {"tests": self.tests} =20 with open(self.test_file, "w", encoding=3D"utf-8") as fp: - yaml.safe_dump(data, fp, sort_keys=3DFalse, default_style=3D"|= ", - default_flow_style=3DFalse, allow_unicode=3DTru= e) + yaml.dump(data, fp, + sort_keys=3DFalse, width=3D120, indent=3D2, + default_flow_style=3DFalse, allow_unicode=3DTrue, + explicit_start=3DFalse, explicit_end=3DFalse) --=20 2.53.0 From nobody Fri Apr 3 20:51:58 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 66F7B38656E; Mon, 23 Mar 2026 09:10:59 +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=1774257059; cv=none; b=IkH7Q1f7nRnnN98BGQl5vdz3ddW+m7sIAM9AORxUkzNFG5Igucq1y2QWyWTh+ypY64Trl4EJzcLefEWwVx0jOYr/qfmTT5dzwycnDByJxtV71cvBKDm/hVX4wOAxFxK86YraYorbDLDpIgoMutl9b62miH5fA2ULtV8B34aExZw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774257059; c=relaxed/simple; bh=addHFIswpEMO6DerS1Dkay2VaZwGGhyLKO3G7KAZQRU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=l+nw9WeszjbNPMKqolq8R0AxI/DXonJHCQfHLyZ0PuFWFks7RbfOkQ+H+bla5CvyFvn0SPwDJSzEgjFd7TO6HvieEz78axjgRui12zzFEXT3ENzlXlJZKs5HrkQKXRoGGP5TCCUIEIT26MmX797xICZgTns4szrh6TZz6+P8tac= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=nj5m6xCE; 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="nj5m6xCE" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C3823C4AF09; Mon, 23 Mar 2026 09:10:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1774257059; bh=addHFIswpEMO6DerS1Dkay2VaZwGGhyLKO3G7KAZQRU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nj5m6xCEY2Y40B7doo3Lzagn6pzdmOj4OerQgs/UHg+/y+2YS5cWNawwXmRv3iBIO slJfxOyMHjfIvoQadbgNptl3eE9j6pZxWqiAvNDig9yGAjP7pByviEqzaKY1aVG4Rx pCAkON4b5u3S+dPXdV1KHGQOmeowyu0lB1bINLn9bQrz6t/TFAxZ0vTshcfgBDlGly 7U3lYjmEbfZd6w6iF8CfeTD8wa3dAbnbkbQCxFrlpyEpFOGHvf6HEGhayTx5rt2hE1 hF1a/C3AHiOzyP0v82NB0RTaGWZwMdoPcOVry7yjvObsmkAgsqyKoS1SxzaS6n4Xg/ OwE8qh7TAm2HQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1w4bJI-00000002yWY-24Id; Mon, 23 Mar 2026 10:10:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Randy Dunlap Subject: [PATCH 05/10] docs: kdoc-test.yaml: add more tests Date: Mon, 23 Mar 2026 10:10:48 +0100 Message-ID: <75af93a45151b630c94b7f77637d173e6119fd41.1774256269.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.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 extra tests to check if the new "var" type is properly handled and to cover mutex context annotations. Co-developed-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab --- tools/unittests/kdoc-test.yaml | 1548 +++++++++++++++++++++++++++++++- 1 file changed, 1546 insertions(+), 2 deletions(-) diff --git a/tools/unittests/kdoc-test.yaml b/tools/unittests/kdoc-test.yaml index b6e04f10ccdb..14d36daa1bba 100644 --- a/tools/unittests/kdoc-test.yaml +++ b/tools/unittests/kdoc-test.yaml @@ -22,7 +22,6 @@ tests: */ int func1(char *arg1) { return 0; }; =20 - expected: - rst: | .. c:function:: int func1 (char *arg1) @@ -134,7 +133,6 @@ tests: =20 always return 0. =20 - # TODO: how to handle timestamps at .TH? man: | .TH "func2" 9 "February 2026" "" "Kernel API Manual" .SH NAME @@ -152,3 +150,1549 @@ tests: .SH "SEE ALSO" .PP Kernel file \fBfunc2.c\fR + +- name: doc_with_complex_table + description: Test if complex tables are handled + fname: mock.c + source: | + /** + * DOC: Supported input formats and encodings + * + * Depending on the Hardware configuration of the Controller IP, it s= upports + * a subset of the following input formats and encodings on its inter= nal + * 48bit bus. + * + * +----------------------+----------------------------------+-------= -----------------------+ + * | Format Name | Format Code | Encodi= ngs | + * +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ + * | RGB 4:4:4 8bit | ``MEDIA_BUS_FMT_RGB888_1X24`` | ``V4L2= _YCBCR_ENC_DEFAULT`` | + * +----------------------+----------------------------------+-------= -----------------------+ + * | RGB 4:4:4 10bits | ``MEDIA_BUS_FMT_RGB101010_1X30`` | ``V4L2= _YCBCR_ENC_DEFAULT`` | + * +----------------------+----------------------------------+-------= -----------------------+ + */ + expected: + - man: | + .TH "Supported input formats and encodings" 9 "March 2026" "" "Ker= nel API Manual" + .SH "Supported input formats and encodings" + Depending on the Hardware configuration of the Controller IP, it s= upports + a subset of the following input formats and encodings on its inter= nal + 48bit bus. + .PP + + + .TS + box; + l l l. + \fBFormat Name\fP \fBFormat Code\fP \fBEncodings\fP + _ + RGB 4:4:4 8bit ``MEDIA_BUS_FMT_RGB888_1X24 V4L2_YCBCR_ENC_DEFAULT + RGB 4:4:4 10bits MEDIA_BUS_FMT_RGB101010_1X30 V4L2_YCBCR_ENC_DEFAU= LT`` + .TE + .SH "SEE ALSO" + .PP + Kernel file \fBmock.c\fR + + rst: |- + .. _Supported input formats and encodings: + **Supported input formats and encodings** + Depending on the Hardware configuration of the Controller IP, it s= upports + a subset of the following input formats and encodings on its inter= nal + 48bit bus. + +----------------------+----------------------------------+-------= -----------------------+ + | Format Name | Format Code | Encodi= ngs | + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ + | RGB 4:4:4 8bit | ``MEDIA_BUS_FMT_RGB888_1X24`` | ``V4L2= _YCBCR_ENC_DEFAULT`` | + +----------------------+----------------------------------+-------= -----------------------+ + | RGB 4:4:4 10bits | ``MEDIA_BUS_FMT_RGB101010_1X30`` | ``V4L2= _YCBCR_ENC_DEFAULT`` | + +----------------------+----------------------------------+-------= -----------------------+ +- name: func_with_ascii_artwork + description: Test if ascii artwork is properly output + fname: mock.c + source: | + /** + * add_cxl_resources() - reflect CXL fixed memory windows in iomem_re= source + * @cxl_res: A standalone resource tree where each CXL window is a si= bling + * + * Walk each CXL window in @cxl_res and add it to iomem_resource pote= ntially + * expanding its boundaries to ensure that any conflicting resources = become + * children. If a window is expanded it may then conflict with a anot= her window + * entry and require the window to be truncated or trimmed. Consider = this + * situation:: + * + * |-- "CXL Window 0" --||----- "CXL Window 1" -----| + * |--------------- "System RAM" -------------| + * + * ...where platform firmware has established as System RAM resource = across 2 + * windows, but has left some portion of window 1 for dynamic CXL reg= ion + * provisioning. In this case "Window 0" will span the entirety of th= e "System + * RAM" span, and "CXL Window 1" is truncated to the remaining tail p= ast the end + * of that "System RAM" resource. + */ + static int add_cxl_resources(struct resource *cxl_res); + expected: + - man: |- + .TH "add_cxl_resources" 9 "March 2026" "" "Kernel API Manual" + .SH NAME + add_cxl_resources \- reflect CXL fixed memory windows in iomem_res= ource + .SH SYNOPSIS + .B "int" add_cxl_resources + .BI "(struct resource *cxl_res " ");" + .SH ARGUMENTS + .IP "cxl_res" 12 + A standalone resource tree where each CXL window is a sibling + .SH "DESCRIPTION" + Walk each CXL window in \fIcxl_res\fP and add it to iomem_resource= potentially + expanding its boundaries to ensure that any conflicting resources = become + children. If a window is expanded it may then conflict with a anot= her window + entry and require the window to be truncated or trimmed. Consider = this + situation: + .nf + + |-- "CXL Window 0" --||----- "CXL Window 1" -----| + |--------------- "System RAM" -------------| + + + .fi + .PP + + \&...where platform firmware has established as System RAM resourc= e across 2 + windows, but has left some portion of window 1 for dynamic CXL reg= ion + provisioning. In this case "Window 0" will span the entirety of th= e "System + RAM" span, and "CXL Window 1" is truncated to the remaining tail p= ast the end + of that "System RAM" resource. + .SH "SEE ALSO" + .PP + Kernel file \fBmock.c\fR + rst: | + .. c:function:: int add_cxl_resources (struct resource *cxl_res) + + reflect CXL fixed memory windows in iomem_resource + + .. container:: kernelindent + + **Parameters** + + ``struct resource *cxl_res`` + A standalone resource tree where each CXL window is a sibling + + **Description** + + Walk each CXL window in **cxl_res** and add it to iomem_resource= potentially + expanding its boundaries to ensure that any conflicting resource= s become + children. If a window is expanded it may then conflict with a an= other window + entry and require the window to be truncated or trimmed. Conside= r this + situation:: + + |-- "CXL Window 0" --||----- "CXL Window 1" -----| + |--------------- "System RAM" -------------| + + ...where platform firmware has established as System RAM resourc= e across 2 + windows, but has left some portion of window 1 for dynamic CXL r= egion + provisioning. In this case "Window 0" will span the entirety of = the "System + RAM" span, and "CXL Window 1" is truncated to the remaining tail= past the end + of that "System RAM" resource. + +- name: simple_tables + description: Test formatting two simple tables + fname: mock.c + source: | + /** + * bitmap_onto - translate one bitmap relative to another + * @dst: resulting translated bitmap + * @orig: original untranslated bitmap + * @relmap: bitmap relative to which translated + * @bits: number of bits in each of these bitmaps + * + * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D + * @orig tmp @dst + * 0 0 40 + * 1 1 41 + * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D + * + * And: + * + * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D + * @orig tmp @dst + * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D + * 9 9 95 + * 10 0 40 [#f1]_ + * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D + */ + void bitmap_onto(unsigned long *dst, const unsigned long *orig, + const unsigned long *relmap, unsigned int bits); + expected: + - man: | + .TH "bitmap_onto" 9 "March 2026" "" "Kernel API Manual" + .SH NAME + bitmap_onto \- translate one bitmap relative to another + .SH SYNOPSIS + .B "void" bitmap_onto + .BI "(unsigned long *dst " "," + .BI "const unsigned long *orig " "," + .BI "const unsigned long *relmap " "," + .BI "unsigned int bits " ");" + .SH ARGUMENTS + .IP "dst" 12 + resulting translated bitmap + .IP "orig" 12 + original untranslated bitmap + .IP "relmap" 12 + bitmap relative to which translated + .IP "bits" 12 + number of bits in each of these bitmaps + .SH "DESCRIPTION" + + .TS + box; + l l l. + \fIorig\fP tmp \fIdst\fP + 0 0 40 + 1 1 41 + .TE + .PP + + And: + .PP + + + .TS + box; + l l l. + \fIorig\fP tmp \fIdst\fP + .TE + 9 9 95 + 10 0 40 [#f1]_ + .SH "SEE ALSO" + .PP + Kernel file \fBmock.c\fR + + rst: | + .. c:function:: void bitmap_onto (unsigned long *dst, const unsign= ed long *orig, const unsigned long *relmap, unsigned int bits) + + translate one bitmap relative to another + + .. container:: kernelindent + + **Parameters** + + ``unsigned long *dst`` + resulting translated bitmap + + ``const unsigned long *orig`` + original untranslated bitmap + + ``const unsigned long *relmap`` + bitmap relative to which translated + + ``unsigned int bits`` + number of bits in each of these bitmaps + + **Description** + + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + **orig** tmp **dst** + 0 0 40 + 1 1 41 + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + + And: + + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + **orig** tmp **dst** + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + 9 9 95 + 10 0 40 [#f1]_ + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + +# +# Variable tests from Randy Dunlap's testset +# +- name: unsigned_long_var_on_uppercase + description: Test an unsigned long varaible in uppercase + fname: mock-vars.c + source: | + /** + * var ROOT_DEV - system root device + * + * @ROOT_DEV is either the successful root device or the root device + * that failed boot in the boot failure message. + */ + unsigned long ROOT_DEV; + expected: + - man: | + .TH "var ROOT_DEV" 9 "February 2026" "" "Kernel API Manual" + .SH NAME + ROOT_DEV \- system root device + .SH SYNOPSIS + unsigned long ROOT_DEV; + .SH "Description" + \fIROOT_DEV\fP is either the successful root device or the root devi= ce + that failed boot in the boot failure message. + .SH "SEE ALSO" + .PP + Kernel file \fBmock-vars.c\fR + rst: | + .. c:macro:: ROOT_DEV + + ``unsigned long ROOT_DEV;`` + + system root device + + **Description** + + **ROOT_DEV** is either the successful root device or the root devi= ce + that failed boot in the boot failure message. +- name: enum_var + description: Test an enum var with __read_mostly + fname: mock-vars.c + source: | + /** + * var system_state - system state used during boot or suspend/hiberna= te/resume + * + * @system_state can be used during boot to determine if it is safe to + * make certain calls to other parts of the kernel. It can also be used + * during suspend/hibernate or resume to determine the order of actions + * that need to be executed. The numerical values of system_state are + * sometimes used in numerical ordering tests, so the relative values + * must not be altered. + */ + enum system_states system_state __read_mostly; + expected: + - man: | + .TH "var system_state" 9 "February 2026" "" "Kernel API Manual" + .SH NAME + system_state \- system state used during boot or suspend/hibernate/r= esume + .SH SYNOPSIS + enum system_states system_state __read_mostly; + .SH "Description" + \fIsystem_state\fP can be used during boot to determine if it is saf= e to + make certain calls to other parts of the kernel. It can also be used + during suspend/hibernate or resume to determine the order of actions + that need to be executed. The numerical values of system_state are + sometimes used in numerical ordering tests, so the relative values + must not be altered. + .SH "SEE ALSO" + .PP + Kernel file \fBmock-vars.c\fR + rst: | + .. c:macro:: system_state + + ``enum system_states system_state __read_mostly;`` + + system state used during boot or suspend/hibernate/resume + + **Description** + + **system_state** can be used during boot to determine if it is saf= e to + make certain calls to other parts of the kernel. It can also be us= ed + during suspend/hibernate or resume to determine the order of actio= ns + that need to be executed. The numerical values of system_state are + sometimes used in numerical ordering tests, so the relative values + must not be altered. +- name: char_pointer_var + description: Test char * var with __ro_after_init + fname: mock-vars.c + source: | + /** + * var saved_command_line - kernel's command line, saved from use at + * any later time in the kernel. + */ + char *saved_command_line __ro_after_init; + expected: + - man: | + .TH "var saved_command_line" 9 "February 2026" "" "Kernel API Manua= l" + .SH NAME + saved_command_line \- kernel's command line, saved from use at any l= ater time in the kernel. + .SH SYNOPSIS + char *saved_command_line __ro_after_init; + .SH "SEE ALSO" + .PP + Kernel file \fBmock-vars.c\fR + rst: | + .. c:macro:: saved_command_line + + ``char *saved_command_line __ro_after_init;`` + + kernel's command line, saved from use at any later time in the ker= nel. +- name: unsigned_long_with_default + description: Test an unsigned long var that is set to a default value + fname: mock-vars.c + source: | + /** + * var loop_per_jiffy - calculated loop count needed to consume one ji= ffy + * of time + */ + unsigned long loops_per_jiffy =3D (1<<12); + expected: + - man: | + .TH "var loops_per_jiffy" 9 "February 2026" "" "Kernel API Manual" + .SH NAME + loops_per_jiffy \- calculated loop count needed to consume one jiffy= of time + .SH SYNOPSIS + unsigned long loops_per_jiffy =3D (1<<12); + .SH "Initialization" + default: (1<<12) + .SH "SEE ALSO" + .PP + Kernel file \fBmock-vars.c\fR + rst: | + .. c:macro:: loops_per_jiffy + + ``unsigned long loops_per_jiffy =3D (1<<12);`` + + calculated loop count needed to consume one jiffy of time + + **Initialization** + + default: ``(1<<12)`` +- name: unsigned_long + description: test a simple unsigned long variable. + fname: mock-vars.c + source: | + /** + * var preset_lpj - lpj (loops per jiffy) value set from kernel + * command line using "lpj=3DVALUE" + * + * See Documentation/admin-guide/kernel-parameters.txt ("lpj=3D") for = details. + */ + unsigned long preset_lpj; + expected: + - man: | + .TH "var preset_lpj" 9 "February 2026" "" "Kernel API Manual" + .SH NAME + preset_lpj \- lpj (loops per jiffy) value set from kernel command li= ne using "lpj=3DVALUE" + .SH SYNOPSIS + unsigned long preset_lpj; + .SH "Description" + See Documentation/admin-guide/kernel-parameters.txt ("lpj=3D") for d= etails. + .SH "SEE ALSO" + .PP + Kernel file \fBmock-vars.c\fR + rst: | + .. c:macro:: preset_lpj + + ``unsigned long preset_lpj;`` + + lpj (loops per jiffy) value set from kernel command line using "lp= j=3DVALUE" + + **Description** + + See Documentation/admin-guide/kernel-parameters.txt ("lpj=3D") for= details. +- name: char_array + description: test a char array variable + fname: mock-vars.c + source: | + /** + * var linux_proc_banner - text used from /proc/version file + * + * * first %s is sysname (e.g., "Linux") + * * second %s is release + * * third %s is version + */ + char linux_proc_banner[]; + expected: + - man: | + .TH "var linux_proc_banner" 9 "February 2026" "" "Kernel API Manual" + .SH NAME + linux_proc_banner \- text used from /proc/version file + .SH SYNOPSIS + char linux_proc_banner[]; + .SH "Description" + .IP \[bu] + first s is sysname (e.g., "Linux") + .IP \[bu] + second s is release + .IP \[bu] + third s is version + .SH "SEE ALSO" + .PP + Kernel file \fBmock-vars.c\fR + rst: | + .. c:macro:: linux_proc_banner + + ``char linux_proc_banner[];`` + + text used from /proc/version file + + **Description** + + * first ``s`` is sysname (e.g., "Linux") + * second ``s`` is release + * third ``s`` is version +- name: const_char_array + description: test a const char array variable + fname: mock-vars.c + source: | + /** + * var linux_banner - Linux boot banner, usually printed at boot time + */ + const char linux_banner[]; + expected: + - man: | + .TH "var linux_banner" 9 "February 2026" "" "Kernel API Manual" + .SH NAME + linux_banner \- Linux boot banner, usually printed at boot time + .SH SYNOPSIS + const char linux_banner[]; + .SH "SEE ALSO" + .PP + Kernel file \fBmock-vars.c\fR + rst: | + .. c:macro:: linux_banner + + ``const char linux_banner[];`` + + Linux boot banner, usually printed at boot time +- name: static_atomic64_t_var + description: test a static atomi64_t variable + fname: mock-vars.c + source: | + /** + * var diskseq - unique sequence number for block device instances + * + * Allows userspace to associate uevents to the lifetime of a device + */ + static atomic64_t diskseq; + expected: + - man: | + .TH "var diskseq" 9 "February 2026" "" "Kernel API Manual" + .SH NAME + diskseq \- unique sequence number for block device instances + .SH SYNOPSIS + static atomic64_t diskseq; + .SH "Description" + Allows userspace to associate uevents to the lifetime of a device + .SH "SEE ALSO" + .PP + Kernel file \fBmock-vars.c\fR + rst: | + .. c:macro:: diskseq + + ``static atomic64_t diskseq;`` + + unique sequence number for block device instances + + **Description** + + Allows userspace to associate uevents to the lifetime of a device +- name: unsigned_long_on_init + description: test an unsigned long var at "init" with a different timest= amp. + fname: init/mock-vars.c + source: | + /** + * var rtnl_mutex - historical global lock for networking control oper= ations. + * + * @rtnl_mutex is used to serialize rtnetlink requests + * and protect all kernel internal data structures related to networki= ng. + * + * See Documentation/networking/netdevices.rst for details. + * Often known as the rtnl_lock, although rtnl_lock is a kernel functi= on. + */ + unsigned long rtnl_mutex; + expected: + - man: | + .TH "var rtnl_mutex" 9 "February 2026" "init" "Kernel API Manual" + .SH NAME + rtnl_mutex \- historical global lock for networking control operatio= ns. + .SH SYNOPSIS + unsigned long rtnl_mutex; + .SH "Description" + \fIrtnl_mutex\fP is used to serialize rtnetlink requests + and protect all kernel internal data structures related to networkin= g. + .PP + + See Documentation/networking/netdevices.rst for details. + Often known as the rtnl_lock, although rtnl_lock is a kernel functio= n. + .SH "SEE ALSO" + .PP + Kernel file \fBinit/mock-vars.c\fR + rst: | + .. c:macro:: rtnl_mutex + + ``unsigned long rtnl_mutex;`` + + historical global lock for networking control operations. + + **Description** + + **rtnl_mutex** is used to serialize rtnetlink requests + and protect all kernel internal data structures related to networkin= g. + + See Documentation/networking/netdevices.rst for details. + Often known as the rtnl_lock, although rtnl_lock is a kernel functio= n. + + +- name: struct_kcov + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * struct kcov - kcov descriptor (one per opened debugfs file). + * State transitions of the descriptor: + * + * - initial state after open() + * - then there must be a single ioctl(KCOV_INIT_TRACE) call + * - then, mmap() call (several calls are allowed but not useful) + * - then, ioctl(KCOV_ENABLE, arg), where arg is + * KCOV_TRACE_PC - to trace only the PCs + * or + * KCOV_TRACE_CMP - to trace only the comparison operands + * - then, ioctl(KCOV_DISABLE) to disable the task. + * + * Enabling/disabling ioctls can be repeated (only one task a time all= owed). + */ + struct kcov { + /** + * @refcount: Reference counter. We keep one for: + * - opened file descriptor + * - task with enabled coverage (we can't unwire it from anot= her task) + * - each code section for remote coverage collection + */ + refcount_t refcount; + /** + * @lock: The lock protects mode, size, area and t. + */ + spinlock_t lock; + /** + * @mode: the kcov_mode + */ + enum kcov_mode mode __guarded_by(&lock); + /** + * @size: Size of arena (in long's). + */ + unsigned int size __guarded_by(&lock); + /** + * @area: Coverage buffer shared with user space. + */ + void *area __guarded_by(&lock); + /** + * @t: Task for which we collect coverage, or NULL. + */ + struct task_struct *t __guarded_by(&lock); + /** + * @remote: Collecting coverage from remote (background) threa= ds. + */ + bool remote; + /** + * @remote_size: Size of remote area (in long's). + */ + unsigned int remote_size; + /** + * @sequence: Sequence is incremented each time kcov is reenab= led, + * used by kcov_remote_stop(), see the comment there. + */ + int sequence; + }; + expected: + - man: | + .TH "struct kcov" 9 "February 2026" "mock_tests" "Kernel API Manual" + .SH NAME + struct kcov \- kcov descriptor (one per opened debugfs file). State = transitions of the descriptor: + .SH SYNOPSIS + struct kcov { + .br + .BI " refcount_t refcount;" + .br + .BI " spinlock_t lock;" + .br + .BI " enum kcov_mode mode;" + .br + .BI " unsigned int size;" + .br + .BI " void *area;" + .br + .BI " struct task_struct *t;" + .br + .BI " bool remote;" + .br + .BI " unsigned int remote_size;" + .br + .BI " int sequence;" + .br + .BI " + }; + .br + + .SH Members + .IP "refcount" 12 + Reference counter. We keep one for: + .IP \[bu] + opened file descriptor + .IP \[bu] + task with enabled coverage (we can't unwire it from another task) + .IP \[bu] + each code section for remote coverage collection + .IP "lock" 12 + The lock protects mode, size, area and t. + .IP "mode" 12 + the kcov_mode + .IP "size" 12 + Size of arena (in long's). + .IP "area" 12 + Coverage buffer shared with user space. + .IP "t" 12 + Task for which we collect coverage, or NULL. + .IP "remote" 12 + Collecting coverage from remote (background) threads. + .IP "remote_size" 12 + Size of remote area (in long's). + .IP "sequence" 12 + Sequence is incremented each time kcov is reenabled, + used by \fBkcov_remote_stop\fP, see the comment there. + .SH "Description" + .IP \[bu] + initial state after \fBopen\fP + .IP \[bu] + then there must be a single ioctl(KCOV_INIT_TRACE) call + .IP \[bu] + then, \fBmmap\fP call (several calls are allowed but not useful) + .IP \[bu] + then, ioctl(KCOV_ENABLE, arg), where arg is + KCOV_TRACE_PC - to trace only the PCs + or + KCOV_TRACE_CMP - to trace only the comparison operands + .IP \[bu] + then, ioctl(KCOV_DISABLE) to disable the task. + .PP + + Enabling/disabling ioctls can be repeated (only one task a time allo= wed). + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:struct:: kcov + + kcov descriptor (one per opened debugfs file). State transitions o= f the descriptor: + + .. container:: kernelindent + + **Definition**:: + + struct kcov { + refcount_t refcount; + spinlock_t lock; + enum kcov_mode mode; + unsigned int size; + void *area; + struct task_struct *t; + bool remote; + unsigned int remote_size; + int sequence; + }; + + **Members** + + ``refcount`` + Reference counter. We keep one for: + - opened file descriptor + - task with enabled coverage (we can't unwire it from another t= ask) + - each code section for remote coverage collection + + ``lock`` + The lock protects mode, size, area and t. + + ``mode`` + the kcov_mode + + ``size`` + Size of arena (in long's). + + ``area`` + Coverage buffer shared with user space. + + ``t`` + Task for which we collect coverage, or NULL. + + ``remote`` + Collecting coverage from remote (background) threads. + + ``remote_size`` + Size of remote area (in long's). + + ``sequence`` + Sequence is incremented each time kcov is reenabled, + used by kcov_remote_stop(), see the comment there. + + + **Description** + + - initial state after open() + - then there must be a single ioctl(KCOV_INIT_TRACE) call + - then, mmap() call (several calls are allowed but not useful) + - then, ioctl(KCOV_ENABLE, arg), where arg is + KCOV_TRACE_PC - to trace only the PCs + or + KCOV_TRACE_CMP - to trace only the comparison operands + - then, ioctl(KCOV_DISABLE) to disable the task. + + Enabling/disabling ioctls can be repeated (only one task a time all= owed). + +- name: pool_offset + description: mock_tests/kdoc-drop-ctx-lock.c line 83 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * var pool_offset - Offset to the unused space in the currently used = pool. + * + */ + size_t pool_offset __guarded_by(&pool_lock) =3D DEPOT_POOL_SIZE; + expected: + - man: | + .TH "var pool_offset" 9 "February 2026" "mock_tests" "Kernel API Ma= nual" + .SH NAME + pool_offset \- Offset to the unused space in the currently used pool. + .SH SYNOPSIS + size_t pool_offset __guarded_by(&pool_lock) =3D DEPOT_POOL_SIZE; + .SH "Initialization" + default: DEPOT_POOL_SIZE + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:macro:: pool_offset + + ``size_t pool_offset __guarded_by(&pool_lock) =3D DEPOT_POOL_SIZE;= `` + + Offset to the unused space in the currently used pool. + + **Initialization** + + default: ``DEPOT_POOL_SIZE`` +- name: free_stacks + description: mock_tests/kdoc-drop-ctx-lock.c line 88 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * var free_stacks - Freelist of stack records within stack_pools. + * + */ + __guarded_by(&pool_lock) LIST_HEAD(free_stacks); + expected: + - man: | + .TH "var free_stacks" 9 "February 2026" "mock_tests" "Kernel API Ma= nual" + .SH NAME + free_stacks \- Freelist of stack records within stack_pools. + .SH SYNOPSIS + __guarded_by(&pool_lock) LIST_HEAD(free_stacks); + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:macro:: free_stacks + + ``__guarded_by(&pool_lock) LIST_HEAD(free_stacks);`` + + Freelist of stack records within stack_pools. +- name: stack_pools + description: mock_tests/kdoc-drop-ctx-lock.c line 94 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * var stack_pools - Array of memory regions that store stack records. + * + */ + void **stack_pools __pt_guarded_by(&pool_lock); + expected: + - man: | + .TH "var stack_pools" 9 "February 2026" "mock_tests" "Kernel API Ma= nual" + .SH NAME + stack_pools \- Array of memory regions that store stack records. + .SH SYNOPSIS + void **stack_pools __pt_guarded_by(&pool_lock); + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:macro:: stack_pools + + ``void **stack_pools __pt_guarded_by(&pool_lock);`` + + Array of memory regions that store stack records. +- name: prepare_report_consumer + description: mock_tests/kdoc-drop-ctx-lock.c line 103 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * prepare_report_consumer - prepare the report consumer + * @flags: flags + * @ai: not that AI + * @other_info: yes that + */ + bool prepare_report_consumer(unsigned long *flags, + const struct access_info *ai, + struct other_info *other_info) + __cond_acquires(true, &report_lock) + { + expected: + - man: | + .TH "prepare_report_consumer" 9 "February 2026" "mock_tests" "Kerne= l API Manual" + .SH NAME + prepare_report_consumer \- prepare the report consumer + .SH SYNOPSIS + .B "bool" prepare_report_consumer + .BI "(unsigned long *flags " "," + .BI "const struct access_info *ai " "," + .BI "struct other_info *other_info " ");" + .SH ARGUMENTS + .IP "flags" 12 + flags + .IP "ai" 12 + not that AI + .IP "other_info" 12 + yes that + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: bool prepare_report_consumer (unsigned long *flags, = const struct access_info *ai, struct other_info *other_info) + + prepare the report consumer + + .. container:: kernelindent + + **Parameters** + + ``unsigned long *flags`` + flags + + ``const struct access_info *ai`` + not that AI + + ``struct other_info *other_info`` + yes that +- name: tcp_sigpool_start + description: mock_tests/kdoc-drop-ctx-lock.c line 117 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * tcp_sigpool_start - start a tcp message of @id, using @c + * @id: TCP message ID + * @c: the &tcp_sigpool to use + */ + int tcp_sigpool_start(unsigned int id, struct tcp_sigpool *c) __cond_a= cquires(0, RCU_BH) + { + expected: + - man: | + .TH "tcp_sigpool_start" 9 "February 2026" "mock_tests" "Kernel API = Manual" + .SH NAME + tcp_sigpool_start \- start a tcp message of @id, using @c + .SH SYNOPSIS + .B "int" tcp_sigpool_start + .BI "(unsigned int id " "," + .BI "struct tcp_sigpool *c " ");" + .SH ARGUMENTS + .IP "id" 12 + TCP message ID + .IP "c" 12 + the \fItcp_sigpool\fP to use + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: int tcp_sigpool_start (unsigned int id, struct tcp_s= igpool *c) + + start a tcp message of **id**, using **c** + + .. container:: kernelindent + + **Parameters** + + ``unsigned int id`` + TCP message ID + + ``struct tcp_sigpool *c`` + the :c:type:`tcp_sigpool` to use +- name: undo_report_consumer + description: mock_tests/kdoc-drop-ctx-lock.c line 129 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * undo_report_consumer - teardown a report consumer + * @flags: those flags + * @ai: not that AI + * @other_info: yes that + */ + bool undo_report_consumer(unsigned long *flags, + const struct access_info *ai, + struct other_info *other_info) + __cond_releases(true, &report_lock) + { + expected: + - man: | + .TH "undo_report_consumer" 9 "February 2026" "mock_tests" "Kernel A= PI Manual" + .SH NAME + undo_report_consumer \- teardown a report consumer + .SH SYNOPSIS + .B "bool" undo_report_consumer + .BI "(unsigned long *flags " "," + .BI "const struct access_info *ai " "," + .BI "struct other_info *other_info " ");" + .SH ARGUMENTS + .IP "flags" 12 + those flags + .IP "ai" 12 + not that AI + .IP "other_info" 12 + yes that + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: bool undo_report_consumer (unsigned long *flags, con= st struct access_info *ai, struct other_info *other_info) + + teardown a report consumer + + .. container:: kernelindent + + **Parameters** + + ``unsigned long *flags`` + those flags + + ``const struct access_info *ai`` + not that AI + + ``struct other_info *other_info`` + yes that +- name: debugfs_enter_cancellation + description: mock_tests/kdoc-drop-ctx-lock.c line 143 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * debugfs_enter_cancellation - begin a cancellation operation on @file + * @file: the target file + * @cancellation: the operation to execute + */ + void debugfs_enter_cancellation(struct file *file, + struct debugfs_cancellation *cancellat= ion) __acquires(cancellation) + { } + expected: + - man: | + .TH "debugfs_enter_cancellation" 9 "February 2026" "mock_tests" "Ke= rnel API Manual" + .SH NAME + debugfs_enter_cancellation \- begin a cancellation operation on @file + .SH SYNOPSIS + .B "void" debugfs_enter_cancellation + .BI "(struct file *file " "," + .BI "struct debugfs_cancellation *cancellation " ");" + .SH ARGUMENTS + .IP "file" 12 + the target file + .IP "cancellation" 12 + the operation to execute + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: void debugfs_enter_cancellation (struct file *file, = struct debugfs_cancellation *cancellation) + + begin a cancellation operation on **file** + + .. container:: kernelindent + + **Parameters** + + ``struct file *file`` + the target file + + ``struct debugfs_cancellation *cancellation`` + the operation to execute +- name: debugfs_leave_cancellation + description: mock_tests/kdoc-drop-ctx-lock.c line 152 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * debugfs_leave_cancellation - wrapup the cancellation operation on @= file + * @file: the target file + * @cancellation: the operation to wrapup + */ + void debugfs_leave_cancellation(struct file *file, + struct debugfs_cancellation *cancellat= ion) __releases(cancellation) + { } + expected: + - man: | + .TH "debugfs_leave_cancellation" 9 "February 2026" "mock_tests" "Ke= rnel API Manual" + .SH NAME + debugfs_leave_cancellation \- wrapup the cancellation operation on @= file + .SH SYNOPSIS + .B "void" debugfs_leave_cancellation + .BI "(struct file *file " "," + .BI "struct debugfs_cancellation *cancellation " ");" + .SH ARGUMENTS + .IP "file" 12 + the target file + .IP "cancellation" 12 + the operation to wrapup + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: void debugfs_leave_cancellation (struct file *file, = struct debugfs_cancellation *cancellation) + + wrapup the cancellation operation on **file** + + .. container:: kernelindent + + **Parameters** + + ``struct file *file`` + the target file + + ``struct debugfs_cancellation *cancellation`` + the operation to wrapup +- name: acpi_os_acquire_lock + description: mock_tests/kdoc-drop-ctx-lock.c line 161 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * acpi_os_acquire_lock - Acquire a spinlock. + * @lockp: pointer to the spinlock_t. + */ + acpi_cpu_flags acpi_os_acquire_lock(acpi_spinlock lockp) + __acquires(lockp) + { + expected: + - man: | + .TH "acpi_os_acquire_lock" 9 "February 2026" "mock_tests" "Kernel A= PI Manual" + .SH NAME + acpi_os_acquire_lock \- Acquire a spinlock. + .SH SYNOPSIS + .B "acpi_cpu_flags" acpi_os_acquire_lock + .BI "(acpi_spinlock lockp " ");" + .SH ARGUMENTS + .IP "lockp" 12 + pointer to the spinlock_t. + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: acpi_cpu_flags acpi_os_acquire_lock (acpi_spinlock l= ockp) + + Acquire a spinlock. + + .. container:: kernelindent + + **Parameters** + + ``acpi_spinlock lockp`` + pointer to the spinlock_t. +- name: acpi_os_release_lock + description: mock_tests/kdoc-drop-ctx-lock.c line 172 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * acpi_os_release_lock - Release a spinlock. + * @lockp: pointer to the spinlock_t. + * @not_used: these flags are not used. + */ + void acpi_os_release_lock(acpi_spinlock lockp, acpi_cpu_flags not_used) + __releases(lockp) + { + expected: + - man: | + .TH "acpi_os_release_lock" 9 "February 2026" "mock_tests" "Kernel A= PI Manual" + .SH NAME + acpi_os_release_lock \- Release a spinlock. + .SH SYNOPSIS + .B "void" acpi_os_release_lock + .BI "(acpi_spinlock lockp " "," + .BI "acpi_cpu_flags not_used " ");" + .SH ARGUMENTS + .IP "lockp" 12 + pointer to the spinlock_t. + .IP "not_used" 12 + these flags are not used. + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: void acpi_os_release_lock (acpi_spinlock lockp, acpi= _cpu_flags not_used) + + Release a spinlock. + + .. container:: kernelindent + + **Parameters** + + ``acpi_spinlock lockp`` + pointer to the spinlock_t. + + ``acpi_cpu_flags not_used`` + these flags are not used. +- name: tx + description: mock_tests/kdoc-drop-ctx-lock.c line 183 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * tx - transmit message ID @id + * @id: message ID to transmit + */ + int tx(int id) __must_hold(&txlock) + { + expected: + - man: | + .TH "tx" 9 "February 2026" "mock_tests" "Kernel API Manual" + .SH NAME + tx \- transmit message ID @id + .SH SYNOPSIS + .B "int" tx + .BI "(int id " ");" + .SH ARGUMENTS + .IP "id" 12 + message ID to transmit + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: int tx (int id) + + transmit message ID **id** + + .. container:: kernelindent + + **Parameters** + + ``int id`` + message ID to transmit +- name: contend_for_bm + description: mock_tests/kdoc-drop-ctx-lock.c line 192 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * contend_for_bm - try to become the bus master + * @card: the &fw_card (describes the bus) + */ + enum bm_contention_outcome contend_for_bm(struct fw_card *card) + __must_hold(&card->lock) + { + expected: + - man: | + .TH "contend_for_bm" 9 "February 2026" "mock_tests" "Kernel API Man= ual" + .SH NAME + contend_for_bm \- try to become the bus master + .SH SYNOPSIS + .B "enum bm_contention_outcome" contend_for_bm + .BI "(struct fw_card *card " ");" + .SH ARGUMENTS + .IP "card" 12 + the \fIfw_card\fP (describes the bus) + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: enum bm_contention_outcome contend_for_bm (struct fw= _card *card) + + try to become the bus master + + .. container:: kernelindent + + **Parameters** + + ``struct fw_card *card`` + the :c:type:`fw_card` (describes the bus) +- name: prepare_report_producer + description: mock_tests/kdoc-drop-ctx-lock.c line 202 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * prepare_report_producer - prepare the report producer + * @flags: still flags + * @ai: some AI + * @other_info: Populate @other_info; requires that the provided + * @other_info not in use. + */ + void prepare_report_producer(unsigned long *flags, + const struct access_info *ai, + struct other_info *other_info) + __must_not_hold(&report_lock) + { } + expected: + - man: | + .TH "prepare_report_producer" 9 "February 2026" "mock_tests" "Kerne= l API Manual" + .SH NAME + prepare_report_producer \- prepare the report producer + .SH SYNOPSIS + .B "void" prepare_report_producer + .BI "(unsigned long *flags " "," + .BI "const struct access_info *ai " "," + .BI "struct other_info *other_info " ");" + .SH ARGUMENTS + .IP "flags" 12 + still flags + .IP "ai" 12 + some AI + .IP "other_info" 12 + Populate \fIother_info\fP; requires that the provided + \fIother_info\fP not in use. + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: void prepare_report_producer (unsigned long *flags, = const struct access_info *ai, struct other_info *other_info) + + prepare the report producer + + .. container:: kernelindent + + **Parameters** + + ``unsigned long *flags`` + still flags + + ``const struct access_info *ai`` + some AI + + ``struct other_info *other_info`` + Populate **other_info**; requires that the provided + **other_info** not in use. +- name: crypto_alg_lookup + description: mock_tests/kdoc-drop-ctx-lock.c line 215 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * __crypto_alg_lookup() - lookup the algorithm by name/type/mask + * @name: name to search for + * @type: type to search for + * @mask: mask to match + */ + struct crypto_alg *__crypto_alg_lookup(const char *name, u32 type, + u32 mask) + __must_hold_shared(&crypto_alg_sem) + { + expected: + - man: | + .TH "__crypto_alg_lookup" 9 "February 2026" "mock_tests" "Kernel AP= I Manual" + .SH NAME + __crypto_alg_lookup \- lookup the algorithm by name/type/mask + .SH SYNOPSIS + .B "struct crypto_alg *" __crypto_alg_lookup + .BI "(const char *name " "," + .BI "u32 type " "," + .BI "u32 mask " ");" + .SH ARGUMENTS + .IP "name" 12 + name to search for + .IP "type" 12 + type to search for + .IP "mask" 12 + mask to match + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: struct crypto_alg * __crypto_alg_lookup (const char = *name, u32 type, u32 mask) + + lookup the algorithm by name/type/mask + + .. container:: kernelindent + + **Parameters** + + ``const char *name`` + name to search for + + ``u32 type`` + type to search for + + ``u32 mask`` + mask to match +- name: down_read_trylock + description: mock_tests/kdoc-drop-ctx-lock.c line 228 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * down_read_trylock - trylock for reading + * @sem: the semaphore to try to lock + * + * Returns: 1 if successful, 0 if contention + */ + extern int down_read_trylock(struct rw_semaphore *sem) __cond_acquires= _shared(true, sem); + expected: + - man: | + .TH "down_read_trylock" 9 "February 2026" "mock_tests" "Kernel API = Manual" + .SH NAME + down_read_trylock \- trylock for reading + .SH SYNOPSIS + .B "int" down_read_trylock + .BI "(struct rw_semaphore *sem " ");" + .SH ARGUMENTS + .IP "sem" 12 + the semaphore to try to lock + .SH "RETURN" + 1 if successful, 0 if contention + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: int down_read_trylock (struct rw_semaphore *sem) + + trylock for reading + + .. container:: kernelindent + + **Parameters** + + ``struct rw_semaphore *sem`` + the semaphore to try to lock + + **Return** + + 1 if successful, 0 if contention +- name: tomoyo_read_lock + description: mock_tests/kdoc-drop-ctx-lock.c line 236 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * tomoyo_read_lock - Take lock for protecting policy. + * + * Returns: index number for tomoyo_read_unlock(). + */ + int tomoyo_read_lock(void) + __acquires_shared(&tomoyo_ss) + { + expected: + - man: | + .TH "tomoyo_read_lock" 9 "February 2026" "mock_tests" "Kernel API M= anual" + .SH NAME + tomoyo_read_lock \- Take lock for protecting policy. + .SH SYNOPSIS + .B "int" tomoyo_read_lock + .BI "(void " ");" + .SH ARGUMENTS + .IP "void" 12 + no arguments + .SH "RETURN" + index number for \fBtomoyo_read_unlock\fP. + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: int tomoyo_read_lock (void) + + Take lock for protecting policy. + + .. container:: kernelindent + + **Parameters** + + ``void`` + no arguments + + **Return** + + index number for tomoyo_read_unlock(). +- name: tomoyo_read_unlock + description: mock_tests/kdoc-drop-ctx-lock.c line 247 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * tomoyo_read_unlock - Release lock for protecting policy. + * + * @idx: Index number returned by tomoyo_read_lock(). + */ + void tomoyo_read_unlock(int idx) + __releases_shared(&tomoyo_ss) + { } + expected: + - man: | + .TH "tomoyo_read_unlock" 9 "February 2026" "mock_tests" "Kernel API= Manual" + .SH NAME + tomoyo_read_unlock \- Release lock for protecting policy. + .SH SYNOPSIS + .B "void" tomoyo_read_unlock + .BI "(int idx " ");" + .SH ARGUMENTS + .IP "idx" 12 + Index number returned by \fBtomoyo_read_lock\fP. + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: void tomoyo_read_unlock (int idx) + + Release lock for protecting policy. + + .. container:: kernelindent + + **Parameters** + + ``int idx`` + Index number returned by tomoyo_read_lock(). +- name: c_stop + description: mock_tests/kdoc-drop-ctx-lock.c line 256 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * c_stop - stop the seq_file iteration + * @m: the &struct seq_file + * @p: handle + */ + void c_stop(struct seq_file *m, void *p) + __releases_shared(&crypto_alg_sem) + { } + expected: + - man: | + .TH "c_stop" 9 "February 2026" "mock_tests" "Kernel API Manual" + .SH NAME + c_stop \- stop the seq_file iteration + .SH SYNOPSIS + .B "void" c_stop + .BI "(struct seq_file *m " "," + .BI "void *p " ");" + .SH ARGUMENTS + .IP "m" 12 + the \fIstruct seq_file\fP + .IP "p" 12 + handle + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: void c_stop (struct seq_file *m, void *p) + + stop the seq_file iteration + + .. container:: kernelindent + + **Parameters** + + ``struct seq_file *m`` + the :c:type:`struct seq_file ` + + ``void *p`` + handle +- name: spin_lock + description: mock_tests/kdoc-drop-ctx-lock.c line 265 + fname: mock_tests/kdoc-drop-ctx-lock.c + source: | + /** + * spin_lock - spin until the @lock is acquired + * @lock: the spinlock + */ + void spin_lock(spinlock_t *lock) + __acquires(lock) __no_context_analysis + { } + expected: + - man: | + .TH "spin_lock" 9 "February 2026" "mock_tests" "Kernel API Manual" + .SH NAME + spin_lock \- spin until the @lock is acquired + .SH SYNOPSIS + .B "void" spin_lock + .BI "(spinlock_t *lock " ");" + .SH ARGUMENTS + .IP "lock" 12 + the spinlock + .SH "SEE ALSO" + .PP + Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR + rst: | + .. c:function:: void spin_lock (spinlock_t *lock) + + spin until the **lock** is acquired + + .. container:: kernelindent + + **Parameters** + + ``spinlock_t *lock`` + the spinlock --=20 2.53.0 From nobody Fri Apr 3 20:51:58 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 F0D75386452; Mon, 23 Mar 2026 09:10:58 +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=1774257059; cv=none; b=V+iUoIYoiGjevZ3wdss8sAablpVE6/43ghHHIVL1evLwGPFLimyWziXohDp3K+pIILnO7Mewx5U3dDFpjYAbKQI1d7zm25gu2BENBpPbdOS0MFqBB6bcqJMvqxQfsYt+26wztMeHOnjq5kfS5Wi83+WILJNg9Owo5cGhioKG4Cc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774257059; c=relaxed/simple; bh=a05Vd8qHdqT2ZnuRBv0SnC55B9ItAT/pJgyul5M5lIE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=uo2QzlvUDVhyztB7zmwyaF8U1wOW/Ptp1F3Ub50ytE/jCKNNYpxHBPBLXB7f07rWbydX71TLrXSGc2aWVShtgt2uNhM58Y56sPJ62VbAct+DGHenqR7LrHFYTLbQybqvLHYiCvGlsRGhOTDbGRp6qkQ9WsS9KHImUQibuQ+fIiQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=W1nF5H6k; 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="W1nF5H6k" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C3C41C4AF0C; Mon, 23 Mar 2026 09:10:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1774257058; bh=a05Vd8qHdqT2ZnuRBv0SnC55B9ItAT/pJgyul5M5lIE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=W1nF5H6klfS2mJn9aIZd43KfU7bK+Qy/KezTPgU5AJJZFaq93mlK330jq6vyGTPCm dQDuZMJ/ZXhxG2PzIZ3HQi8VJxHSpDDE8MbUbYk6T2Nlb5spvakGvj/coIvHKg0aG7 ZN/UmOSiuc97oML14CsMoTaIor+bCyqTaDwnipAPFomANaOHLr1KllkSuun6cQkxuS 6dx307FQI8jgsOsLIu/VOYoeoPyJ7vZzZRNYtV11IaNFwunc5HgnoszVH0pJ/iIrX/ G3LocYeFG+uRcL+K+IC7cP6yw/zdubiXZ/yYT52jyn9m/uYF4NK07PVx+lBnpH/Ua/ R6QURklPtj5QA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1w4bJI-00000002yWc-2B6s; Mon, 23 Mar 2026 10:10:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 06/10] docs: kdoc_output: fix handling of simple tables Date: Mon, 23 Mar 2026 10:10:49 +0100 Message-ID: X-Mailer: git-send-email 2.53.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 Fix check for simple table delimiters. ReST simple tables use "=3D" instead of "-". I ended testing it with a table modified from a complex one, using "--- --- ---", instead of searching for a real Kernel example. Only noticed when adding an unit test and seek for an actual example from kernel-doc markups. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 1b54117dbe19..2bfcd356654b 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -846,14 +846,14 @@ class ManFormat(OutputFormat): colspec_row =3D None =20 pos =3D [] - for m in KernRe(r'\-+').finditer(lines[i]): + for m in KernRe(r'\=3D+').finditer(lines[i]): pos.append((m.start(), m.end() - 1)) =20 i +=3D 1 while i < len(lines): line =3D lines[i] =20 - if KernRe(r"^\s*[\-]+[ \t\-]+$").match(line): + if KernRe(r"^\s*[\=3D]+[ \t\=3D]+$").match(line): i +=3D 1 break =20 @@ -969,7 +969,7 @@ class ManFormat(OutputFormat): self.data +=3D text continue =20 - if KernRe(r"^\-+[ \t]\-[ \t\-]+$").match(line): + if KernRe(r"^\=3D+[ \t]\=3D[ \t\=3D]+$").match(line): i, text =3D self.simple_table(lines, i) self.data +=3D text continue --=20 2.53.0 From nobody Fri Apr 3 20:51:58 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 4B1E238655B; Mon, 23 Mar 2026 09:10:59 +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=1774257059; cv=none; b=BJ74oC9kXXM3HeZJfpy+6avQKXOFJ7jMMVbdAZxJ0SF2CqaZrLmOUXT0HSuDB6/nrYnipYVI3devJx33TvUF+pYC4GJvn5UvU7TwOjX/q1EqsfafAz3F31Geuo0tTHTL8j5otTeojmdHr9jQMm0yNVKObvpFzqhzLHRLmUbQjyU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774257059; c=relaxed/simple; bh=I+Z90ZgRcAKwP9M+teTDbwHynmYojrMLzCXd+nUPEDY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=k6yCIh7Zy/TrJc3JLA6Rjc3VWx1nbeF4o4bZrDFV1/m78YJrF02Gtcy5YSegtaj+UgyVkR+KBpyOkKdkRvTCAwVcKjREMMaSwYMUI6OB6tWsTOpjT7jq+xUkk0OuoxcuZFFEHQmIPiACH9W6UT2FQJSaCK6Wglc2J5PaysE1rZY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=NQwOqVfJ; 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="NQwOqVfJ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D0289C2BCB6; Mon, 23 Mar 2026 09:10:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1774257059; bh=I+Z90ZgRcAKwP9M+teTDbwHynmYojrMLzCXd+nUPEDY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=NQwOqVfJ7c8LIdpQ33R80m2rSH5vlLo5zbcwpKf51Ww6zmrcwhVaV/NC8S3BUCwR4 xPPTRz4DILklEvqhPOkEIQGdHSJiwHax7lrKFhs4WLovnGpt8i3LdKUorzeN3x3hSL 0QLQj9k6A9GTxLPOvbcyPOCwRfDbG1pEmea0FvHG+XNXdYyFeHff8UU4jVKG76HIdk /GQxskLVmNbP/0/knM6UiRSTxjOgxAnt+5zCVyPw9/d0iU22Hx3eRb8/bYHdSv4vJB xqek3BADD/kqSRLQ905ksBAtfh03kC9dPFjEIDUi8HS8IU0Te4yK/MaaTUkQ95rA1/ N+HBaCkAfQNlg== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1w4bJI-00000002yWg-2IMT; Mon, 23 Mar 2026 10:10:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Aleksandr Loktionov , Randy Dunlap Subject: [PATCH 07/10] docs: kdoc: better handle source when producing YAML output Date: Mon, 23 Mar 2026 10:10:50 +0100 Message-ID: <77902dafabb5c3250486aa2dc1568d5fafa95c5b.1774256269.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The current logic was storing symbols source code on a list, not linked to the actual KdocItem. While this works fine when kernel-doc markups are OK, on places where there is a "/**" without a valid kernel-doc markup, it ends that the 1:1 match between source code and KdocItem doesn't happen, causing problems to generate the YAML output. Fix it by storing the source code directly into the KdocItem structure. This shouldn't affect performance or memory footprint, except when --yaml option is used. While here, add a __repr__() function for KdocItem, as it helps debugging it. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_files.py | 8 +- tools/lib/python/kdoc/kdoc_item.py | 6 +- tools/lib/python/kdoc/kdoc_parser.py | 100 ++++++++++++------------ tools/lib/python/kdoc/kdoc_yaml_file.py | 28 +++---- tools/unittests/test_kdoc_parser.py | 9 +++ 5 files changed, 79 insertions(+), 72 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kd= oc_files.py index 5a299ed44d62..2428cfc4e843 100644 --- a/tools/lib/python/kdoc/kdoc_files.py +++ b/tools/lib/python/kdoc/kdoc_files.py @@ -203,10 +203,6 @@ class KernelFiles(): =20 self.results[fname] =3D entries =20 - source =3D doc.get_source() - if source: - self.source[fname] =3D source - def process_export_file(self, fname): """ Parses ``EXPORT_SYMBOL*`` macros from a single Kernel source file. @@ -294,7 +290,6 @@ class KernelFiles(): =20 self.errors =3D 0 self.results =3D {} - self.source =3D {} =20 self.files =3D set() self.export_files =3D set() @@ -364,8 +359,7 @@ class KernelFiles(): function_table, enable_lineno, no_doc_sections) =20 - self.test_file.output_symbols(fname, symbols, - self.source.get(fname)) + self.test_file.output_symbols(fname, symbols) =20 continue =20 diff --git a/tools/lib/python/kdoc/kdoc_item.py b/tools/lib/python/kdoc/kdo= c_item.py index fe08cac861c2..a7aa6e1e4c1c 100644 --- a/tools/lib/python/kdoc/kdoc_item.py +++ b/tools/lib/python/kdoc/kdoc_item.py @@ -14,7 +14,8 @@ class KdocItem: then pass into the output modules. """ =20 - def __init__(self, name, fname, type, start_line, **other_stuff): + def __init__(self, name, fname, type, start_line, + **other_stuff): self.name =3D name self.fname =3D fname self.type =3D type @@ -60,6 +61,9 @@ class KdocItem: def __getitem__(self, key): return self.get(key) =20 + def __repr__(self): + return f"KdocItem({self.name}, {self.fname}, {self.type}, {self.de= claration_start_line})" + @classmethod def from_dict(cls, d): """Create a KdocItem from a plain dict.""" diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index a10e64589d76..74af7ae47aa4 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -265,9 +265,6 @@ class KernelDoc: # Place all potential outputs into an array self.entries =3D [] =20 - # When store_src is true, the kernel-doc source content is stored = here - self.source =3D None - # # We need Python 3.7 for its "dicts remember the insertion # order" guarantee @@ -720,13 +717,14 @@ class KernelDoc: return declaration =20 =20 - def dump_struct(self, ln, proto): + def dump_struct(self, ln, proto, source): """ Store an entry for a ``struct`` or ``union`` """ # # Do the basic parse to get the pieces of the declaration. # + source =3D source proto =3D trim_private_members(proto) struct_parts =3D self.split_struct_proto(proto) if not struct_parts: @@ -756,10 +754,11 @@ class KernelDoc: declaration_name) self.check_sections(ln, declaration_name, decl_type) self.output_declaration(decl_type, declaration_name, + source=3Dsource, definition=3Dself.format_struct_decl(decla= ration), purpose=3Dself.entry.declaration_purpose) =20 - def dump_enum(self, ln, proto): + def dump_enum(self, ln, proto, source): """ Store an ``enum`` inside self.entries array. """ @@ -767,6 +766,7 @@ class KernelDoc: # Strip preprocessor directives. Note that this depends on the # trailing semicolon we added in process_proto_type(). # + source =3D source proto =3D trim_private_members(proto) proto =3D KernRe(r'#\s*((define|ifdef|if)\s+|endif)[^;]*;', flags= =3Dre.S).sub('', proto) # @@ -831,9 +831,10 @@ class KernelDoc: f"Excess enum value '@{k}' description in '{= declaration_name}'") =20 self.output_declaration('enum', declaration_name, + source=3Dsource, purpose=3Dself.entry.declaration_purpose) =20 - def dump_var(self, ln, proto): + def dump_var(self, ln, proto, source): """ Store variables that are part of kAPI. """ @@ -846,6 +847,7 @@ class KernelDoc: # # Store the full prototype before modifying it # + source =3D source full_proto =3D proto declaration_name =3D None =20 @@ -895,32 +897,34 @@ class KernelDoc: default_val =3D default_val.lstrip("=3D").strip() =20 self.output_declaration("var", declaration_name, + source=3Dsource, full_proto=3Dfull_proto, default_val=3Ddefault_val, purpose=3Dself.entry.declaration_purpose) =20 - def dump_declaration(self, ln, prototype): + def dump_declaration(self, ln, prototype, source): """ Store a data declaration inside self.entries array. """ =20 if self.entry.decl_type =3D=3D "enum": - self.dump_enum(ln, prototype) + self.dump_enum(ln, prototype, source) elif self.entry.decl_type =3D=3D "typedef": - self.dump_typedef(ln, prototype) + self.dump_typedef(ln, prototype, source) elif self.entry.decl_type in ["union", "struct"]: - self.dump_struct(ln, prototype) + self.dump_struct(ln, prototype, source) elif self.entry.decl_type =3D=3D "var": - self.dump_var(ln, prototype) + self.dump_var(ln, prototype, source) else: # This would be a bug self.emit_message(ln, f'Unknown declaration type: {self.entry.= decl_type}') =20 - def dump_function(self, ln, prototype): + def dump_function(self, ln, prototype, source): """ Store a function or function macro inside self.entries array. """ =20 + source =3D source found =3D func_macro =3D False return_type =3D '' decl_type =3D 'function' @@ -1013,13 +1017,14 @@ class KernelDoc: # Store the result. # self.output_declaration(decl_type, declaration_name, + source=3Dsource, typedef=3D('typedef' in return_type), functiontype=3Dreturn_type, purpose=3Dself.entry.declaration_purpose, func_macro=3Dfunc_macro) =20 =20 - def dump_typedef(self, ln, proto): + def dump_typedef(self, ln, proto, source): """ Store a ``typedef`` inside self.entries array. """ @@ -1030,6 +1035,8 @@ class KernelDoc: typedef_ident =3D r'\*?\s*(\w\S+)\s*' typedef_args =3D r'\s*\((.*)\);' =20 + source =3D source + typedef1 =3D KernRe(typedef_type + r'\(' + typedef_ident + r'\)' += typedef_args) typedef2 =3D KernRe(typedef_type + typedef_ident + typedef_args) =20 @@ -1050,6 +1057,7 @@ class KernelDoc: self.create_parameter_list(ln, 'function', args, ',', declarat= ion_name) =20 self.output_declaration('function', declaration_name, + source=3Dsource, typedef=3DTrue, functiontype=3Dreturn_type, purpose=3Dself.entry.declaration_purpo= se) @@ -1067,6 +1075,7 @@ class KernelDoc: return =20 self.output_declaration('typedef', declaration_name, + source=3Dsource, purpose=3Dself.entry.declaration_purpo= se) return =20 @@ -1104,7 +1113,7 @@ class KernelDoc: function_set.add(symbol) return True =20 - def process_normal(self, ln, line): + def process_normal(self, ln, line, source): """ STATE_NORMAL: looking for the ``/**`` to begin everything. """ @@ -1118,7 +1127,7 @@ class KernelDoc: # next line is always the function name self.state =3D state.NAME =20 - def process_name(self, ln, line): + def process_name(self, ln, line, source): """ STATE_NAME: Looking for the "name - description" line """ @@ -1251,7 +1260,7 @@ class KernelDoc: return False =20 =20 - def process_decl(self, ln, line): + def process_decl(self, ln, line, source): """ STATE_DECLARATION: We've seen the beginning of a declaration. """ @@ -1280,7 +1289,7 @@ class KernelDoc: self.emit_msg(ln, f"bad line: {line}") =20 =20 - def process_special(self, ln, line): + def process_special(self, ln, line, source): """ STATE_SPECIAL_SECTION: a section ending with a blank line. """ @@ -1331,7 +1340,7 @@ class KernelDoc: # Unknown line, ignore self.emit_msg(ln, f"bad line: {line}") =20 - def process_body(self, ln, line): + def process_body(self, ln, line, source): """ STATE_BODY: the bulk of a kerneldoc comment. """ @@ -1345,7 +1354,7 @@ class KernelDoc: # Unknown line, ignore self.emit_msg(ln, f"bad line: {line}") =20 - def process_inline_name(self, ln, line): + def process_inline_name(self, ln, line, source): """STATE_INLINE_NAME: beginning of docbook comments within a proto= type.""" =20 if doc_inline_sect.search(line): @@ -1363,10 +1372,10 @@ class KernelDoc: # Don't let it add partial comments at the code, as breaks the # logic meant to remove comments from prototypes. # - self.process_proto_type(ln, "/**\n" + line) + self.process_proto_type(ln, "/**\n" + line, source) # else ... ?? =20 - def process_inline_text(self, ln, line): + def process_inline_text(self, ln, line, source): """STATE_INLINE_TEXT: docbook comments within a prototype.""" =20 if doc_inline_end.search(line): @@ -1452,7 +1461,7 @@ class KernelDoc: =20 return proto =20 - def process_proto_function(self, ln, line): + def process_proto_function(self, ln, line, source): """Ancillary routine to process a function prototype.""" =20 # strip C99-style comments to end of line @@ -1494,10 +1503,10 @@ class KernelDoc: # # ... and we're done # - self.dump_function(ln, self.entry.prototype) + self.dump_function(ln, self.entry.prototype, source) self.reset_state(ln) =20 - def process_proto_type(self, ln, line): + def process_proto_type(self, ln, line, source): """ Ancillary routine to process a type. """ @@ -1527,7 +1536,7 @@ class KernelDoc: elif chunk =3D=3D '}': self.entry.brcount -=3D 1 elif chunk =3D=3D ';' and self.entry.brcount <=3D 0: - self.dump_declaration(ln, self.entry.prototype) + self.dump_declaration(ln, self.entry.prototype, source) self.reset_state(ln) return # @@ -1536,7 +1545,7 @@ class KernelDoc: # self.entry.prototype +=3D ' ' =20 - def process_proto(self, ln, line): + def process_proto(self, ln, line, source): """STATE_PROTO: reading a function/whatever prototype.""" =20 if doc_inline_oneline.search(line): @@ -1548,17 +1557,18 @@ class KernelDoc: self.state =3D state.INLINE_NAME =20 elif self.entry.decl_type =3D=3D 'function': - self.process_proto_function(ln, line) + self.process_proto_function(ln, line, source) =20 else: - self.process_proto_type(ln, line) + self.process_proto_type(ln, line, source) =20 - def process_docblock(self, ln, line): + def process_docblock(self, ln, line, source): """STATE_DOCBLOCK: within a ``DOC:`` block.""" =20 if doc_end.search(line): self.dump_section() - self.output_declaration("doc", self.entry.identifier) + self.output_declaration("doc", self.entry.identifier, + source=3Dsource) self.reset_state(ln) =20 elif doc_content.search(line): @@ -1596,15 +1606,6 @@ class KernelDoc: state.DOCBLOCK: process_docblock, } =20 - def get_source(self): - """ - Return the file content of the lines handled by kernel-doc at the - latest parse_kdoc() run. - - Returns none if KernelDoc() was not initialized with store_src, - """ - return self.source - def parse_kdoc(self): """ Open and process each line of a C source file. @@ -1618,8 +1619,8 @@ class KernelDoc: prev =3D "" prev_ln =3D None export_table =3D set() - self.source =3D [] self.state =3D state.NORMAL + source =3D "" =20 try: with open(self.fname, "r", encoding=3D"utf8", @@ -1646,7 +1647,11 @@ class KernelDoc: ln, state.name[self.state], line) =20 - prev_state =3D self.state + if self.store_src: + if source and self.state =3D=3D state.NORMAL: + source =3D "" + elif self.state !=3D state.NORMAL: + source +=3D line + "\n" =20 # This is an optimization over the original script. # There, when export_file was used for the same file, @@ -1655,16 +1660,11 @@ class KernelDoc: # if (self.state !=3D state.NORMAL) or \ not self.process_export(export_table, line): + prev_state =3D self.state # Hand this line to the appropriate state handler - self.state_actions[self.state](self, ln, line) - - if self.store_src and prev_state !=3D self.state or se= lf.state !=3D state.NORMAL: - if self.state =3D=3D state.NAME: - # A "/**" was detected. Add a new source eleme= nt - self.source.append({"ln": ln, "data": line + "= \n"}) - else: - # Append to the existing one - self.source[-1]["data"] +=3D line + "\n" + self.state_actions[self.state](self, ln, line, sou= rce) + if prev_state =3D=3D state.NORMAL and self.state != =3D state.NORMAL: + source +=3D line + "\n" =20 self.emit_unused_warnings() =20 diff --git a/tools/lib/python/kdoc/kdoc_yaml_file.py b/tools/lib/python/kdo= c/kdoc_yaml_file.py index 18737abb1176..1e2ae7c59d70 100644 --- a/tools/lib/python/kdoc/kdoc_yaml_file.py +++ b/tools/lib/python/kdoc/kdoc_yaml_file.py @@ -85,7 +85,7 @@ class KDocTestFile(): =20 return d =20 - def output_symbols(self, fname, symbols, source): + def output_symbols(self, fname, symbols): """ Store source, symbols and output strings at self.tests. """ @@ -96,16 +96,10 @@ class KDocTestFile(): kdoc_item =3D [] expected =3D [] =20 - if not symbols and not source: - return - - if not source or len(symbols) !=3D len(source): - print(f"Warning: lengths are different. Ignoring {fname}") - - # Folding without line numbers is too hard. - # The right thing to do here to proceed would be to delete - # not-handled source blocks, as len(source) should be bigger - # than len(symbols) + # + # Source code didn't produce any symbol + # + if not symbols: return =20 base_name =3D "test_" + fname.replace(".", "_").replace("/", "_") @@ -115,9 +109,15 @@ class KDocTestFile(): for i in range(0, len(symbols)): arg =3D symbols[i] =20 - if "KdocItem" in self.yaml_content: + source =3D arg.get("source", "") + + if arg and "KdocItem" in self.yaml_content: msg =3D self.get_kdoc_item(arg) =20 + other_stuff =3D msg.get("other_stuff", {}) + if "source" in other_stuff: + del other_stuff["source"] + expected_dict["kdoc_item"] =3D msg =20 for out_style in self.out_style: @@ -132,9 +132,9 @@ class KDocTestFile(): =20 test =3D { "name": name, - "description": f"{fname} line {source[i]["ln"]}", + "description": f"{fname} line {arg.declaration_start_line}= ", "fname": fname, - "source": source[i]["data"], + "source": source, "expected": [expected_dict] } =20 diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdo= c_parser.py index f2250ef192ce..c4a76ed13dbc 100755 --- a/tools/unittests/test_kdoc_parser.py +++ b/tools/unittests/test_kdoc_parser.py @@ -167,7 +167,16 @@ class GenerateKdocItem(unittest.TestCase): self.assertIsInstance(entry, KdocItem) =20 d =3D vars(entry) + + other_stuff =3D d.get("other_stuff", {}) + if "source" in other_stuff: + del other_stuff["source"] + for key, value in expected.items(): + if key =3D=3D "other_stuff": + if "source" in value: + del value["source"] + result =3D clean_whitespc(d[key], relax_whitespace) value =3D clean_whitespc(value, relax_whitespace) =20 --=20 2.53.0 From nobody Fri Apr 3 20:51:58 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 E9CBB3859F2; Mon, 23 Mar 2026 09:10:58 +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=1774257059; cv=none; b=exlVp5My7c3DyNkPJ6UcEdzSL9IHUXTWf7FPoY9qumNFyIQMk7Loza+HUdMwx8eU0Gwund2i015iQof7lldNh8wtpC2z+k2DBM572rR/w5a/k1a+VLQC9xcMl8CuUpY7HpS4y8DYmG6GJGWAeca/zsaI+PlTc6C5pGsqP/Y07C4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774257059; c=relaxed/simple; bh=BFO+bQXgmdQHXLJcGT6y1ITcuEWmfE5np+ylBh2HDxI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=jFk/j5RpjD7mchPkce9/sjJ1J60Noqt/dnHcIvihNlaCCL1R4PqawgJbGU1reTdQv0tDURvC/4EFdk88gKjwMcOt9wSW7l+Kk44dHimlrbOGscJ6u7pdX+vHlvTDoGbC8u/iqKGA1PdEr72mkTz2DctjlW5ypirVf4YyNwJmz9A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=PO7P1hoE; 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="PO7P1hoE" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C44BAC4AF0D; Mon, 23 Mar 2026 09:10:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1774257058; bh=BFO+bQXgmdQHXLJcGT6y1ITcuEWmfE5np+ylBh2HDxI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PO7P1hoEHznXBS3njW9xi3P8P2o2XTkYtXGMPz9PxRCIoR7Q1Tx5ywBCDPivllZDL CfymcQVyxepQ9okOXRjb8XYFMxsHpbL2btIohOyM9SU7owNrLbzEPjh5C9VEmMKWJH wW/+KS7UIvEmSOztvpaUIMz/6vtpRTudKVg8Rh+ficeiVVe15KSBQH+AuTmbWxd5O4 NJByhMJRsGoFKm+QpV1sZaenA9xU9pzlC/sNznMoXgV6R0xQFU23UCI6XucKhkCCBb r9nBgS5O2UpVc/cymmV6emO3vzt+0tUwB04IDhgvD4EoU5kCCDMpaQdyOjPvje8y8L yaLEbvH9yteYQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1w4bJI-00000002yWk-2P9E; Mon, 23 Mar 2026 10:10:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 08/10] docs: kdoc_yaml_file: use a better name for the tests Date: Mon, 23 Mar 2026 10:10:51 +0100 Message-ID: X-Mailer: git-send-email 2.53.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 always using a name with a number on it, use the name of the object directly whenever possible. When the name is already used, append a number prefix at the end. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_yaml_file.py | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_yaml_file.py b/tools/lib/python/kdo= c/kdoc_yaml_file.py index 1e2ae7c59d70..0be020d50df0 100644 --- a/tools/lib/python/kdoc/kdoc_yaml_file.py +++ b/tools/lib/python/kdoc/kdoc_yaml_file.py @@ -25,6 +25,7 @@ class KDocTestFile(): self.config =3D config self.test_file =3D os.path.expanduser(yaml_file) self.yaml_content =3D yaml_content + self.test_names =3D set() =20 self.tests =3D [] =20 @@ -102,13 +103,10 @@ class KDocTestFile(): if not symbols: return =20 - base_name =3D "test_" + fname.replace(".", "_").replace("/", "_") expected_dict =3D {} start_line=3D1 =20 - for i in range(0, len(symbols)): - arg =3D symbols[i] - + for arg in symbols: source =3D arg.get("source", "") =20 if arg and "KdocItem" in self.yaml_content: @@ -120,6 +118,21 @@ class KDocTestFile(): =20 expected_dict["kdoc_item"] =3D msg =20 + base_name =3D arg.name + if not base_name: + base_name =3D fname + base_name =3D base_name.lower().replace(".", "_").replace("/",= "_") + + + # Don't add duplicated names + i =3D 0 + name =3D base_name + while name in self.test_names: + i +=3D 1 + name =3D f"{base_name}_{i:03d}" + + self.test_names.add(name) + for out_style in self.out_style: if isinstance(out_style, ManFormat): key =3D "man" @@ -128,8 +141,6 @@ class KDocTestFile(): =20 expected_dict[key]=3D out_style.output_symbols(fname, [arg= ]).strip() =20 - name =3D f"{base_name}_{i:03d}" - test =3D { "name": name, "description": f"{fname} line {arg.declaration_start_line}= ", --=20 2.53.0 From nobody Fri Apr 3 20:51:58 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 3683F386546; Mon, 23 Mar 2026 09:10:59 +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=1774257059; cv=none; b=MlcRQglACMX3/en4kZgJyw97PsFays/RWy+lWJYRVgZcOjhYDy9fFnBRB4YigKXtv85ILtzK42JkI3Qnprh1221nlbOjBjuTyOPvUghjbf2CH8mTPbCIy4ftg4B9QU4yjKXLyCNrz1bk8MTHGymGZk9nyylr62Ia/h2s1hhnSGI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774257059; c=relaxed/simple; bh=B3aCLA38CLRmLj2OdM/72Kjt2RpUr22KLeSB8xmgElM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=hswivOg7ufV4mLDjwG5/vzIa65aqM24T8Dtofv4F/lXy3eBQ1+FeCBpeaBG2GUDxndcES+v71fxZXrP3vE+A2nRSOzIAKFWGUKJavE3V3f1HcZlwtz0j8HMRg17d9Yg3lCi7K3bn5P7UGCFG03MLLQv+YWXXQSB0Y6jBhUPrci8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=TXUliePc; 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="TXUliePc" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D4E70C2BCB5; Mon, 23 Mar 2026 09:10:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1774257058; bh=B3aCLA38CLRmLj2OdM/72Kjt2RpUr22KLeSB8xmgElM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=TXUliePctSuleXNB7lIswmJ1RU+MZlluUMK1L/UPs4CyQ42Rskp0zqGMNkYO5cslR 9Ywlxei5OOXHwaEHroPkEfTOZMKttfq2j0+W7qJdajHMGfT/6/u63s9/KSpza9pIB3 vD1skDameln38d42o/LooEo/A83gu9fl70Zo7mls8EsxebowBqC6zd0mhqydK8SsVW 6hxc7gxIYi+NhW8tBVzoKbVQWZ4alf25EGjYy2O31laKXfjPgHUvN45+NEDb58DimZ R6T1TV0UPmdZKS926fIuCfSgz3mwaDRY/o5Ik5kc/Fj0ZX1UQ6soATUHvsUFnsY1dk lAKICe2WbEuiA== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1w4bJI-00000002yWo-2W7X; Mon, 23 Mar 2026 10:10:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 09/10] docs: kdoc_output: raise an error if full_proto not available for var Date: Mon, 23 Mar 2026 10:10:52 +0100 Message-ID: <0c3d9dd25889784b999efdb354ade48264c0e03c.1774256269.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.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 mandatory, but if it is missing, we need to know what symbol had problems. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/kdoc_output.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/k= doc_output.py index 2bfcd356654b..de107ab4a281 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -513,7 +513,9 @@ class RestFormat(OutputFormat): def out_var(self, fname, name, args): oldprefix =3D self.lineprefix ln =3D args.declaration_start_line - full_proto =3D args.other_stuff["full_proto"] + full_proto =3D args.other_stuff.get("full_proto") + if not full_proto: + raise KeyError(f"Can't find full proto for {name} variable") =20 self.lineprefix =3D " " =20 --=20 2.53.0 From nobody Fri Apr 3 20:51:58 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 21DF238645C; Mon, 23 Mar 2026 09:10:59 +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=1774257059; cv=none; b=eCbA6i+x5PvOI3wKwRPOE1dyjJYoOT0YlsrbEp60IDglDtX2osJIh5OWnMGdEMo4rhQ/MYNOtXnM9Jyb56wtGY5khV2vzVFkfU+A38gg3dADAS65lCoL6uPMpwFln78vrvFUGA5o4FKI1loNvADlN46nStI1/0LlzObMGsODNJ0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774257059; c=relaxed/simple; bh=SZbd372k/0FI0Z5e+bMZ4b4koJeDa2OHUSQu+POB+Eg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=gB5nCKyIPdO5ZplZ5gQCHrofCDiz0e8gzJOr3S+tJMTAd9FfEpDHuosE/CNSFxSvu0AJ7k2Lsx+cquI6sNMh2uHpHi/llQ6ZF7Hs5LE3m0s0PpNpgYVYGibhd3hLkZaUncW7iQNtcPXCleZ2h8+bP3EGdB1b1QqAhZVB2oWORag= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZlUeLCsE; 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="ZlUeLCsE" Received: by smtp.kernel.org (Postfix) with ESMTPSA id CDE19C2BCB1; Mon, 23 Mar 2026 09:10:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1774257058; bh=SZbd372k/0FI0Z5e+bMZ4b4koJeDa2OHUSQu+POB+Eg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZlUeLCsEWUOGMRKsvciqc+0sdMlCoolYL2g0TQa69E4dFX1jtrs40Q3r+A7LSp37M 4EyfioJ2fGr+lJ+6YHVy0fKa3IOdS6Y82fcCmI1g0UjQArbz2RrMCfBvlpC14Tju+6 NMWKYiGu782suDfxm67EuJ6ROdoIHVQn06R97obWzoVL3FLK2sqaKoZVW33dMUfn+y sLFf4Um1GPvI42eNnfIF2Ot6DRLRRb+moz5mQtFXvY4XXpJd621vSyIiNUHptgU5dx BwZarOgC8Ok5o2n7LG915ShFr02MKHXjC9ToWLBd8QWNPQjUlpJqm+sNZxpZfhged9 l8SHVVJRE+s/Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99.1) (envelope-from ) id 1w4bJI-00000002yWs-2czj; Mon, 23 Mar 2026 10:10:56 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Aleksandr Loktionov , Mauro Carvalho Chehab Subject: [PATCH 10/10] docs: c_lex.py: store logger on its data Date: Mon, 23 Mar 2026 10:10:53 +0100 Message-ID: <467979dc18149e4b2a7113c178e0cb07919632f2.1774256269.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.53.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 By having the logger stored there, any code using CTokenizer can log messages there. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/kdoc/c_lex.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/tools/lib/python/kdoc/c_lex.py b/tools/lib/python/kdoc/c_lex.py index e01b154f458e..cb95f5172448 100644 --- a/tools/lib/python/kdoc/c_lex.py +++ b/tools/lib/python/kdoc/c_lex.py @@ -177,7 +177,7 @@ class CTokenizer(): # This class is inspired and follows the basic concepts of: # https://docs.python.org/3/library/re.html#writing-a-tokenizer =20 - def __init__(self, source=3DNone, log=3DNone): + def __init__(self, source=3DNone): """ Create a regular expression to handle RE_SCANNER_LIST. =20 @@ -188,6 +188,12 @@ class CTokenizer(): when matching a code via RE_SCANNER. """ =20 + # + # Store logger to allow parser classes to re-use it + # + global log + self.log =3D log + self.tokens =3D [] =20 if not source: --=20 2.53.0