From nobody Tue Dec 16 22:10:39 2025 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 F3F89EAF1; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=poNMj2xnf9uVqok9GGfXts6eOVerkasCSFJGdv9AUi9qyreOBtMsDf7QhEIhHKGAIHAn/Gq2Dy6c6qx61mCMyYhoFVkgIp0i/xzwaYVG4wAS6Ctg3Tb2AlFLxYlMzgnAOcTeuqfPb+WAr+52DgkAiMCfztGt+i7ZG0KkVUk/COA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=VcPpgtY3VQCVYahI46jBKsD0IQlmSoQRt+Yw3exCthU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=TcxG0UkFHAx5fFHx3tUEl9B5xRXfmF8rRjZJ0Q4IdQb1xLtA7V1guLOzyGj9lWNEZ+VcdqKeuHu4SDTIOS3wJ0e1MiWidcYkOukHPSeZgfoXdjebNwCpbLSv2trOSM7sLqAHqT90pyjNwyCEDM4cXtKoDgVg0ZddlQHUdgfCgWU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=pzEmEmmD; 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="pzEmEmmD" Received: by smtp.kernel.org (Postfix) with ESMTPSA id ABE66C4CEE9; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=VcPpgtY3VQCVYahI46jBKsD0IQlmSoQRt+Yw3exCthU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=pzEmEmmDia/8h9o9vspt9axQUlQqbUbHcWZiA1nEKYZ6OFf67FyzD4eYPZ7fEUWR4 W/BtG+ds63lWVpcqjD8JHtKjQGfHVwDw0ARcGCyBg4zIpbfM6F+/3TRbN5WsS27jHi 2OOKb3Qoiypa5MsNd55nzei5d9d3VKRvKOFef0HHfDhAEEgyl5FKH02CpricPoNYLF qBK+Bc0WEGj7Cl8nXHpqnWlCDGXIQ4TXWEduOQzb4k1mkthwM6rc3DrZIPgbVEL3PU 9FcNsM23N3TWSBA7NrjWnD9c1rMb2rRm8oDefzcsTO6YQACFimeHzaeuDyNNU1lVgn AZpIPY7ofcpxA== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRKR-2TDa; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , "Rafael J. Wysocki" , Len Brown , Pavel Machek , linux-kernel@vger.kernel.org, linux-pm@vger.kernel.org Subject: [RFC v2 01/38] docs: power: video.rst: fix a footnote reference Date: Tue, 28 Jan 2025 01:05:50 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Footnotes require an space (or a "\ ") before them, as otherwise Sphinx/Docutils won't understand it. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/power/video.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/power/video.rst b/Documentation/power/video.rst index 337a2ba9f32f..8ab2458d1304 100644 --- a/Documentation/power/video.rst +++ b/Documentation/power/video.rst @@ -190,7 +190,7 @@ Toshiba Portege 3020CT s3_mode (3) Toshiba Satellite 4030CDT s3_mode (3) (S1 also works OK) Toshiba Satellite 4080XCDT s3_mode (3) (S1 also works OK) Toshiba Satellite 4090XCDT ??? [#f1]_ -Toshiba Satellite P10-554 s3_bios,s3_mode (4)[#f3]_ +Toshiba Satellite P10-554 s3_bios,s3_mode (4) [#f3]_ Toshiba M30 (2) xor X with nvidia driver using interna= l AGP Uniwill 244IIO ??? [#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=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 6563D3C14; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; cv=none; b=QtOHjc34sgrrH0xYAkqZ73tJy0S8vLib8ZaB73Czl8/5YWQCd5Ag8fvDZv1Yv9+jlVb+qhtkqhH5OubvIaXf0Nb8U7NfK6IQ/rzhQ+wtYeISf+jQAmtz33x9PW3knFejPvttdHcVtBDdnJCy0uX70b67zmudgUZuvFQneuxSFjM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; c=relaxed/simple; bh=Tm8FYhaC26HmjBWtbEkupMtvOAviwlbF24h5AUzFGQs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=SQjZ1J8pgb2t5KQ4tPu5Jf3ZVti0DlaInI8eYB6yJ84hRxEjkvy+QIxAIw2G4cV4sKhiA/jxpSGF2V+SamXoIabu9NelLCvOjnSZr0bCinGwbGgCEGh/ssX9Da0omP1acJgwKG4Pwx6GQBvxYDflEAqqYp7oM1sJolgn+oKz0CQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=iLGdotL+; 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="iLGdotL+" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 942C5C4CED2; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=Tm8FYhaC26HmjBWtbEkupMtvOAviwlbF24h5AUzFGQs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iLGdotL+XCu9jL2FPU4TWspY5DIYMPMF64MLQyxkAbdh/dY/drz0LqySm5L1BgFgp F0b2VITGBA+K9a78K/SSXC381bnoJesEl+SfA525A8jw8277woBvicYzIaVc7X3wiS RYuaBWQDGiE0IF2JXCm+9n0ZXpZCmIafLp1eYIuQYiYCtLFEUDD7N7Tb6Lrp4VZl99 gnaEZ0kGMIz+qdO0jlBpSDTVRQqATzD0tB2c7Ro+9Kd2ADQyQdDNUfpx08RdgMW5kR acsiVkh6t7i9XeXfyP+zDzh8b6JkDtziQRrPda3JbVBRLpNKrvKsxlls9NUI6KRQfe x45whh4RyNbqQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRKV-2ac5; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , Bingbu Cao , Sakari Ailus , Tianshu Qiu , linux-kernel@vger.kernel.org, linux-media@vger.kernel.org Subject: [RFC v2 02/38] docs: media: ipu3: fix two footnote references Date: Tue, 28 Jan 2025 01:05:51 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Sphinx doesn't process references inside a code block. They need to be before that. Also, one of the refrences is missing a footnote origin. Add it. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/admin-guide/media/ipu3.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/admin-guide/media/ipu3.rst b/Documentation/admin= -guide/media/ipu3.rst index 83b3cd03b35c..b0d42cea5391 100644 --- a/Documentation/admin-guide/media/ipu3.rst +++ b/Documentation/admin-guide/media/ipu3.rst @@ -87,8 +87,8 @@ raw Bayer format that is specific to IPU3. Let us take the example of ov5670 sensor connected to CSI2 port 0, for a 2592x1944 image capture. =20 -Using the media controller APIs, the ov5670 sensor is configured to send -frames in packed raw Bayer format to IPU3 CSI2 receiver. +Using the media controller APIs\ [#f3]_, the ov5670 sensor is configured to +send frames in packed raw Bayer format to IPU3 CSI2 receiver. =20 .. code-block:: none =20 @@ -98,7 +98,7 @@ frames in packed raw Bayer format to IPU3 CSI2 receiver. # and that ov5670 sensor is connected to i2c bus 10 with address 0x36 export SDEV=3D$(media-ctl -d $MDEV -e "ov5670 10-0036") =20 - # Establish the link for the media devices using media-ctl [#f3]_ + # Establish the link for the media devices using media-ctl media-ctl -d $MDEV -l "ov5670:0 -> ipu3-csi2 0:0[1]" =20 # Set the format for the media devices @@ -248,9 +248,9 @@ hence "STILL" mode will need more power and memory band= width than "VIDEO" mode. TNR will be enabled in "VIDEO" mode and bypassed by "STILL" mode. ImgU is running at "VIDEO" mode by default, the user can use v4l2 control V4L2_CID_INTEL_IPU3_MODE (currently defined in -drivers/staging/media/ipu3/include/uapi/intel-ipu3.h) to query and set the -running mode. For user, there is no difference for buffer queueing between= the -"VIDEO" and "STILL" mode, mandatory input and main output node should be +drivers/staging/media/ipu3/include/uapi/intel-ipu3.h\ [#f5]_) to query and= set +the running mode. For user, there is no difference for buffer queueing bet= ween +the "VIDEO" and "STILL" mode, mandatory input and main output node should = be enabled and buffers need be queued, the statistics and the view-finder que= ues are optional. =20 --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 BE8198462; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; cv=none; b=WPy56bmiSV7/Og4KWOEqt3EXldzZFgdCfGzx3jXYj9xCLKs4Uuf1WA2K42nFYtwvDLZNjeYRWHKzdQkzqS8ID59rpeRCRIcC2Gyz6uT9pnOEtdf052OKo0CxmCZLdPUUT6V1aBRfteJIqcHVq5LTBrKjUAvfqyC/ubjttKX9LdQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; c=relaxed/simple; bh=Qfw83Lsvw9YW81iRX0U1pEJiGDlKBK7ODRwFNFgYaqQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=K/sTcyiIrU6RuPkAwA48I7z0HZ1QykoMExa9IUD7SnmwBF4vMFaOaf2W7q2NKmUhIUbU2KY0RsxiQ4UfgtUQkFmUHdxlWloMrgWfoDcYbkujHuLfeXg37sY6+mdnfRhXPo95tDfCnvtGpqZNfUsHWTzrhCv2JGRS3FIvTsnL0O8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=oCw3ncnM; 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="oCw3ncnM" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B2CD2C4CEEB; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=Qfw83Lsvw9YW81iRX0U1pEJiGDlKBK7ODRwFNFgYaqQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=oCw3ncnMSwJFVXYin7ecw9sGmuVVEgSoun/Ci8tV7AZDndK0sk/ezkYQeuOL8Bybh /benV6dn1rTZMgO5OcAncJ1Xr+5/ShybogpSaSirks9Ff7qNGQaUBefuNsqP4WRF06 pFGswKs51hT6T/iJvTsYUiv4AcUNg87OiQ+Hcor/64tVrg1SdWirZTWwtHqZdmdmQL GX+v2TOwPZ+4hSVnqYZrjmtEMARaw46ajpon2hcouDom+G9ztQrE74oB9K0XEbdHGe ksI2n7HFQKKWv5nySzAsHQUpcoCHDWjmpj4WgxYiZHSTYFXFwUxEiupH2PdFn/Gbi2 1FTpMUkv/teog== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRKZ-2hj3; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , Jens Axboe , Ming Lei , linux-block@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [RFC v2 03/38] docs: block: ublk.rst: remove a reference from a dropped text Date: Tue, 28 Jan 2025 01:05:52 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Commit 4093cb5a0634 ("ublk_drv: add mechanism for supporting unprivileged = ublk device") implemented support for unprivileged ublk devices. With that, the text mentioning such issue was removed. However, the footnote is still there. Drop the footnote to remove a documentation build warning. Fixes: 4093cb5a0634 ("ublk_drv: add mechanism for supporting unprivileged u= blk device") Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/block/ublk.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/Documentation/block/ublk.rst b/Documentation/block/ublk.rst index 51665a3e6a50..1e0e7358e14a 100644 --- a/Documentation/block/ublk.rst +++ b/Documentation/block/ublk.rst @@ -333,6 +333,4 @@ References =20 .. [#userspace_readme] https://github.com/ming1/ubdsrv/blob/master/README =20 -.. [#stefan] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha= -x1.localdomain/ - .. [#xiaoguang] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefa= nha-x1.localdomain/ --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 2A2FE1773A; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=mYtTQX8yuaM4LXoCKAqoVQv9OBJkGmKeSkpCtthLqLpJhRiJPkD3Abf4TDKP7vvCqFJoLoNRL/OxVm6H7IUHwGVddi/d/W+Sogi2x2gGvkJjrvMudcqRiJWaAM0bSLUYNYxZI2Tp2svZNFP0zdZZmgaGriTmAUoBbU0fOolTUYk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=OOogPGxX0Vy45ilzrAOiFUxIeadBVZaAODgzfVd0odE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=tfbYkYV0FwP8wgzJbPcmEVDSlKMSekIhCiUx3XERl6JxgxgTCLiMMzoiBe6SaxpoTvWa2apkpbS9wxnIH9OAnAiPPwHdlfi91QOHkT65QFjhN40WfyfR9YrIuTPjpMJx3/SodobCiX4DHtuePi1UUoENXy38Z9uVWoNYmRvOHCI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ticind3S; 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="ticind3S" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9FCDEC4CEE2; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=OOogPGxX0Vy45ilzrAOiFUxIeadBVZaAODgzfVd0odE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ticind3ShbVvYuMJe5rf4O+ul6j5PgQ2w16ywEV0VOXoGUDRnU2WDV0W40g73EK9m Ds51LfoOlb4FXF+28W8CGFMTwLHLlxHsok0mFhsnDDygim5u6hGt4SN8UExLXHP805 ogkDDVoPfhweOtEgjUg6JU5vGk44iJxIy5CAaBBWB7LolxZ5B8c2qhXc7zQaCbjgTp Sk4alcYgCTCwZoM5L0ri3PWdQ1dSF9ZiJ/Nm62DMlQDeUavYvWtF6Wh2BqTm6KjAjd lDE2YOLyR1c1CyB0MELhu8f5VqHcjcPX0Nv3GSyaYEQWhdioQYvxgX0fbJx1oItTs6 9RUYQBNWcZlWw== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRKd-2ozq; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , Randy Dunlap , Vegard Nossum , linux-kernel@vger.kernel.org Subject: [RFC v2 04/38] docs: sphinx: remove kernellog.py file Date: Tue, 28 Jan 2025 01:05:53 +0100 Message-ID: <5a84d6e5fa5d56170024b244e8e374c9dccbf299.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" In the past, there was a need for a wrapper due to different Sphinx versions support (before Sphinx 1.6). This is long gone, and now it is just a wrapper. Get rig of it to simplify the code. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/sphinx/kernel_abi.py | 5 +- Documentation/sphinx/kerneldoc.py | 14 +++--- Documentation/sphinx/kernellog.py | 22 -------- Documentation/sphinx/kfigure.py | 81 ++++++++++++++++-------------- 4 files changed, 53 insertions(+), 69 deletions(-) delete mode 100644 Documentation/sphinx/kernellog.py diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kern= el_abi.py index 5911bd0d7965..8401562cb5d9 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -37,13 +37,13 @@ import os import subprocess import sys import re -import kernellog =20 from docutils import nodes, statemachine from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive from docutils.utils.error_reporting import ErrorString from sphinx.util.docutils import switch_source_input +from sphinx.util import logging =20 __version__ =3D '1.0' =20 @@ -64,6 +64,7 @@ class KernelCmd(Directive): optional_arguments =3D 2 has_content =3D False final_argument_whitespace =3D True + logger =3D logging.getLogger('kernel_abi') =20 option_spec =3D { "debug" : directives.flag, @@ -129,7 +130,7 @@ class KernelCmd(Directive): else: content.append(line, f, ln) =20 - kernellog.info(self.state.document.settings.env.app, "%s: parsed %= i lines" % (fname, n)) + self.logger.info("%s: parsed %i lines" % (fname, n)) =20 if content: self.do_parse(content, node) diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerne= ldoc.py index ec1ddfff1863..be5b8fbf373f 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -39,7 +39,7 @@ from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive import sphinx from sphinx.util.docutils import switch_source_input -import kernellog +from sphinx.util import logging =20 __version__ =3D '1.0' =20 @@ -56,6 +56,7 @@ class KernelDocDirective(Directive): 'functions': directives.unchanged, } has_content =3D False + logger =3D logging.getLogger('kerneldoc') =20 def run(self): env =3D self.state.document.settings.env @@ -109,8 +110,7 @@ class KernelDocDirective(Directive): cmd +=3D [filename] =20 try: - kernellog.verbose(env.app, - 'calling kernel-doc \'%s\'' % (" ".join(cmd)= )) + self.logger.verbose("calling kernel-doc '%s'" % (" ".join(cmd)= )) =20 p =3D subprocess.Popen(cmd, stdout=3Dsubprocess.PIPE, stderr= =3Dsubprocess.PIPE) out, err =3D p.communicate() @@ -120,8 +120,8 @@ class KernelDocDirective(Directive): if p.returncode !=3D 0: sys.stderr.write(err) =20 - kernellog.warn(env.app, - 'kernel-doc \'%s\' failed with return code = %d' % (" ".join(cmd), p.returncode)) + self.logger.warning("kernel-doc '%s' failed with return co= de %d" + % (" ".join(cmd), p.returncode)) return [nodes.error(None, nodes.paragraph(text =3D "kernel= -doc missing"))] elif env.config.kerneldoc_verbosity > 0: sys.stderr.write(err) @@ -148,8 +148,8 @@ class KernelDocDirective(Directive): return node.children =20 except Exception as e: # pylint: disable=3DW0703 - kernellog.warn(env.app, 'kernel-doc \'%s\' processing failed w= ith: %s' % - (" ".join(cmd), str(e))) + self.logger.warning("kernel-doc '%s' processing failed with: %= s" % + (" ".join(cmd), str(e))) return [nodes.error(None, nodes.paragraph(text =3D "kernel-doc= missing"))] =20 def do_parse(self, result, node): diff --git a/Documentation/sphinx/kernellog.py b/Documentation/sphinx/kerne= llog.py deleted file mode 100644 index 0bc00c138cad..000000000000 --- a/Documentation/sphinx/kernellog.py +++ /dev/null @@ -1,22 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 -# -# Sphinx has deprecated its older logging interface, but the replacement -# only goes back to 1.6. So here's a wrapper layer to keep around for -# as long as we support 1.4. -# -# We don't support 1.4 anymore, but we'll keep the wrappers around until -# we change all the code to not use them anymore :) -# -import sphinx -from sphinx.util import logging - -logger =3D logging.getLogger('kerneldoc') - -def warn(app, message): - logger.warning(message) - -def verbose(app, message): - logger.verbose(message) - -def info(app, message): - logger.info(message) diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure= .py index 97166333b727..383f9a695b08 100644 --- a/Documentation/sphinx/kfigure.py +++ b/Documentation/sphinx/kfigure.py @@ -59,12 +59,14 @@ from docutils.parsers.rst import directives from docutils.parsers.rst.directives import images import sphinx from sphinx.util.nodes import clean_astext -import kernellog +from sphinx.util import logging =20 Figure =3D images.Figure =20 __version__ =3D '1.0.0' =20 +logger =3D logging.getLogger('kfigure') + # simple helper # ------------- =20 @@ -170,7 +172,7 @@ def setupTools(app): """ global dot_cmd, dot_Tpdf, convert_cmd, rsvg_convert_cmd # pylint: di= sable=3DW0603 global inkscape_cmd, inkscape_ver_one # pylint: disable=3DW0603 - kernellog.verbose(app, "kfigure: check installed tools ...") + logger.verbose("kfigure: check installed tools ...") =20 dot_cmd =3D which('dot') convert_cmd =3D which('convert') @@ -178,7 +180,7 @@ def setupTools(app): inkscape_cmd =3D which('inkscape') =20 if dot_cmd: - kernellog.verbose(app, "use dot(1) from: " + dot_cmd) + logger.verbose("use dot(1) from: " + dot_cmd) =20 try: dot_Thelp_list =3D subprocess.check_output([dot_cmd, '-Thelp'], @@ -190,10 +192,11 @@ def setupTools(app): dot_Tpdf_ptn =3D b'pdf' dot_Tpdf =3D re.search(dot_Tpdf_ptn, dot_Thelp_list) else: - kernellog.warn(app, "dot(1) not found, for better output quality i= nstall " - "graphviz from https://www.graphviz.org") + logger.warning( + "dot(1) not found, for better output quality install graphviz = from https://www.graphviz.org" + ) if inkscape_cmd: - kernellog.verbose(app, "use inkscape(1) from: " + inkscape_cmd) + logger.verbose("use inkscape(1) from: " + inkscape_cmd) inkscape_ver =3D subprocess.check_output([inkscape_cmd, '--version= '], stderr=3Dsubprocess.DEVNULL) ver_one_ptn =3D b'Inkscape 1' @@ -204,26 +207,27 @@ def setupTools(app): =20 else: if convert_cmd: - kernellog.verbose(app, "use convert(1) from: " + convert_cmd) + logger.verbose("use convert(1) from: " + convert_cmd) else: - kernellog.verbose(app, + logger.verbose( "Neither inkscape(1) nor convert(1) found.\n" - "For SVG to PDF conversion, " - "install either Inkscape (https://inkscape.org/) (preferre= d) or\n" - "ImageMagick (https://www.imagemagick.org)") + "For SVG to PDF conversion, install either Inkscape (https= ://inkscape.org/) (preferred) or\n" + "ImageMagick (https://www.imagemagick.org)" + ) =20 if rsvg_convert_cmd: - kernellog.verbose(app, "use rsvg-convert(1) from: " + rsvg_con= vert_cmd) - kernellog.verbose(app, "use 'dot -Tsvg' and rsvg-convert(1) fo= r DOT -> PDF conversion") + logger.verbose("use rsvg-convert(1) from: " + rsvg_convert_cmd) + logger.verbose("use 'dot -Tsvg' and rsvg-convert(1) for DOT ->= PDF conversion") dot_Tpdf =3D False else: - kernellog.verbose(app, + logger.verbose( "rsvg-convert(1) not found.\n" - " SVG rendering of convert(1) is done by ImageMagick-nati= ve renderer.") + " SVG rendering of convert(1) is done by ImageMagick-nati= ve renderer." + ) if dot_Tpdf: - kernellog.verbose(app, "use 'dot -Tpdf' for DOT -> PDF con= version") + logger.verbose("use 'dot -Tpdf' for DOT -> PDF conversion") else: - kernellog.verbose(app, "use 'dot -Tsvg' and convert(1) for= DOT -> PDF conversion") + logger.verbose("use 'dot -Tsvg' and convert(1) for DOT -> = PDF conversion") =20 =20 # integrate conversion tools @@ -257,13 +261,12 @@ def convert_image(img_node, translator, src_fname=3DN= one): =20 # in kernel builds, use 'make SPHINXOPTS=3D-v' to see verbose messages =20 - kernellog.verbose(app, 'assert best format for: ' + img_node['uri']) + logger.verbose('assert best format for: ' + img_node['uri']) =20 if in_ext =3D=3D '.dot': =20 if not dot_cmd: - kernellog.verbose(app, - "dot from graphviz not available / include D= OT raw.") + logger.verbose("dot from graphviz not available / include DOT = raw.") img_node.replace_self(file2literal(src_fname)) =20 elif translator.builder.format =3D=3D 'latex': @@ -290,10 +293,11 @@ def convert_image(img_node, translator, src_fname=3DN= one): =20 if translator.builder.format =3D=3D 'latex': if not inkscape_cmd and convert_cmd is None: - kernellog.warn(app, - "no SVG to PDF conversion available / in= clude SVG raw." - "\nIncluding large raw SVGs can cause xe= latex error." - "\nInstall Inkscape (preferred) or Image= Magick.") + logger.warning( + "no SVG to PDF conversion available / include SVG raw.= \n" + "Including large raw SVGs can cause xelatex error.\n" + "Install Inkscape (preferred) or ImageMagick." + ) img_node.replace_self(file2literal(src_fname)) else: dst_fname =3D path.join(translator.builder.outdir, fname += '.pdf') @@ -306,15 +310,14 @@ def convert_image(img_node, translator, src_fname=3DN= one): _name =3D dst_fname[len(str(translator.builder.outdir)) + 1:] =20 if isNewer(dst_fname, src_fname): - kernellog.verbose(app, - "convert: {out}/%s already exists and is new= er" % _name) + logger.verbose("convert: {out}/%s already exists and is newer"= % _name) =20 else: ok =3D False mkdir(path.dirname(dst_fname)) =20 if in_ext =3D=3D '.dot': - kernellog.verbose(app, 'convert DOT to: {out}/' + _name) + logger.verbose('convert DOT to: {out}/' + _name) if translator.builder.format =3D=3D 'latex' and not dot_Tp= df: svg_fname =3D path.join(translator.builder.outdir, fna= me + '.svg') ok1 =3D dot2format(app, src_fname, svg_fname) @@ -325,7 +328,7 @@ def convert_image(img_node, translator, src_fname=3DNon= e): ok =3D dot2format(app, src_fname, dst_fname) =20 elif in_ext =3D=3D '.svg': - kernellog.verbose(app, 'convert SVG to: {out}/' + _name) + logger.verbose('convert SVG to: {out}/' + _name) ok =3D svg2pdf(app, src_fname, dst_fname) =20 if not ok: @@ -354,7 +357,7 @@ def dot2format(app, dot_fname, out_fname): with open(out_fname, "w") as out: exit_code =3D subprocess.call(cmd, stdout =3D out) if exit_code !=3D 0: - kernellog.warn(app, + logger.warning( "Error #%d when calling: %s" % (exit_code, " ".j= oin(cmd))) return bool(exit_code =3D=3D 0) =20 @@ -388,13 +391,14 @@ def svg2pdf(app, svg_fname, pdf_fname): pass =20 if exit_code !=3D 0: - kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " "= .join(cmd))) + logger.warning("Error #%d when calling: %s" % + (exit_code, " ".join(cmd))) if warning_msg: - kernellog.warn(app, "Warning msg from %s: %s" - % (cmd_name, str(warning_msg, 'utf-8'))) + logger.warning( "Warning msg from %s: %s" % + (cmd_name, str(warning_msg, 'utf-8'))) elif warning_msg: - kernellog.verbose(app, "Warning msg from %s (likely harmless):\n%s" - % (cmd_name, str(warning_msg, 'utf-8'))) + logger.verbose("Warning msg from %s (likely harmless):\n%s" % + (cmd_name, str(warning_msg, 'utf-8'))) =20 return bool(exit_code =3D=3D 0) =20 @@ -418,7 +422,8 @@ def svg2pdf_by_rsvg(app, svg_fname, pdf_fname): # use stdout and stderr from parent exit_code =3D subprocess.call(cmd) if exit_code !=3D 0: - kernellog.warn(app, "Error #%d when calling: %s" % (exit_code,= " ".join(cmd))) + logger.warning("Error #%d when calling: %s" % + (exit_code, " ".join(cmd))) ok =3D bool(exit_code =3D=3D 0) =20 return ok @@ -513,15 +518,15 @@ def visit_kernel_render(self, node): app =3D self.builder.app srclang =3D node.get('srclang') =20 - kernellog.verbose(app, 'visit kernel-render node lang: "%s"' % (srclan= g)) + logger.verbose('visit kernel-render node lang: "%s"' % srclang) =20 tmp_ext =3D RENDER_MARKUP_EXT.get(srclang, None) if tmp_ext is None: - kernellog.warn(app, 'kernel-render: "%s" unknown / include raw.' %= (srclang)) + logger.warning( 'kernel-render: "%s" unknown / include raw.' % src= lang) return =20 if not dot_cmd and tmp_ext =3D=3D '.dot': - kernellog.verbose(app, "dot from graphviz not available / include = raw.") + logger.verbose("dot from graphviz not available / include raw.") return =20 literal_block =3D node[0] --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 6B2B34400; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; cv=none; b=riQowU6hXMWRo9WY22p0VxRTQiEzLUMMfwcECAAkEfkERXwmmnHtPXIrV5aeW7Cnc4Rd3ugXO3RdK1IgKwVaXSSeeR7N9ucQ3QZNC20EJEw9alnKSAmAHkGRjfAJwE6ug/Z/Y7K8c0+S+6ZuiKifHJML4igsKIDlosSycpUm4ek= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; c=relaxed/simple; bh=us6t/BhA/yQmA2s3pD6tzKRkBi35R7LRCdwJPClSus0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=k0XzD2k665D2XCrufzj4TRA4XFuv45c7JEtEu67vs1YH5/rvQsKppmpBTQBQFmQsrZiBMiRWB5wLciSx8+6TNGbOacgV422JALlcqtlOuQnVdXhoVSXDc1lvJxBT8oNOV5ektAjae2FMS8BKGMqc1KSxNqi83e+/R22Zy2b3Hfk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZoE+68VR; 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="ZoE+68VR" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A59E1C4CEE5; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=us6t/BhA/yQmA2s3pD6tzKRkBi35R7LRCdwJPClSus0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZoE+68VR/fcQQ5BHqCi+RYJwydoRAWcii4EfeuqSfFr0whvaK9QjtLosES+PleInM PnjQie3Esyxkn4I/YVncEuRaBV0W8gY79N/Ew9eBWpxtNK7eWMuEXw4QGDTEE8Z5u+ hB+KJhQROVosTs7RmAdPE0Qpsvd5yImaSCVALEJ5A5MAM1Ps7DKe0xrOlCUczbu+9V ayprTmotQVgQCehCTHQ0KZ3MIqciDX/Z8WyLlc3kYsdWwDR5lxIkVK4dadl+As/854 dygV5fsa5dETKwpExg1YYdNj14Vr0j0/UR8Be11Tqm9Xuvi9A2jgTU7mawFyF37U70 LNyfeFYB5YHCg== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRKh-2w4P; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 05/38] docs: sphinx/kernel_abi: adjust coding style Date: Tue, 28 Jan 2025 01:05:54 +0100 Message-ID: <259b07bffa7907ab8e73939dd5d9f025b2f694a8.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Make pylint and flake8 happier with this module's coding style Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/sphinx/kernel_abi.py | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kern= el_abi.py index 8401562cb5d9..a1887b50a900 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -32,32 +32,30 @@ u""" =20 """ =20 -import codecs import os -import subprocess -import sys import re +import sys =20 -from docutils import nodes, statemachine +from docutils import nodes from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive -from docutils.utils.error_reporting import ErrorString from sphinx.util.docutils import switch_source_input from sphinx.util import logging =20 -__version__ =3D '1.0' +__version__ =3D "1.0" + =20 def setup(app): =20 app.add_directive("kernel-abi", KernelCmd) - return dict( - version =3D __version__ - , parallel_read_safe =3D True - , parallel_write_safe =3D True - ) + return { + "version": __version__, + "parallel_read_safe": True, + "parallel_write_safe": True + } + =20 class KernelCmd(Directive): - u"""KernelABI (``kernel-abi``) directive""" =20 required_arguments =3D 1 @@ -92,15 +90,15 @@ class KernelCmd(Directive): nodeList =3D self.nestedParse(lines, self.arguments[0]) return nodeList =20 - def nestedParse(self, lines, fname): + def nested_parse(self, lines, fname): env =3D self.state.document.settings.env content =3D ViewList() node =3D nodes.section() =20 if "debug" in self.options: code_block =3D "\n\n.. code-block:: rst\n :linenos:\n" - for l in lines.split("\n"): - code_block +=3D "\n " + l + for line in lines.split("\n"): + code_block +=3D "\n " + line lines =3D code_block + "\n\n" =20 line_regex =3D re.compile(r"^\.\. LINENO (\S+)\#([0-9]+)$") --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 66DCD3D6D; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; cv=none; b=uG7FjfkkpmKnaSw++OCfbTIkkhh3famBUWQIl6+gQuv4rwTST9DglRRb8WON7w3FxY22QRqj5voYBot3fByVxuG495c4nIMEg8ArIeQHx2fIGaYZdNfEilKJa845GpgKjGddtPJBx4Yq60WxRV0NamLhIMqnV4FdkV096SGLTdw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; c=relaxed/simple; bh=IFfJ6jqxdTobj9ECUn0r6qKV42rp7aK/OvTRbD8u8YE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=N0BmMyrAUbcV9eaVTNZN06aqbkPpRU9QdnxXwTQvMgQAt0ROcEvHcAtyji4b+jsBmbXlfttiTjA15WHld7SYxK9yY9TeLQrFst4xWk+a5w7xDAEfA5RB4uYGqI98BbO18EkC/8Wdrwv7cHL5E2ZSvMttLGhc9mhmN/xmC8R1D7s= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=OZMGL8mj; 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="OZMGL8mj" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9D293C4CEE3; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=IFfJ6jqxdTobj9ECUn0r6qKV42rp7aK/OvTRbD8u8YE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=OZMGL8mj/vHrvfyGU5ZymZpRstm/e7HpJN2D4HuF9Rfk427vNBRVoO+3/X5wvgEeG 0a1+m1aezzyCvXJyNcrSXZiZfh9Rzq2zgz/oVu9dHRSY2IRYqOViaRLCVGCAN+gsF6 JtMGbZDuQgEvS8jDj47pvcBbIdkhXNEiZGXEMe9d0OUBvXtUhqgs1MAWnKB/TKTLEn PZzT2QYsrA2jQLxuZvcXTwIw1igoNABRdzroNEbcISx3bPyX++09yhL2eW8lmb6BdT WI/YNZYSxE07ZXuqSskFMN/DCae2rstFcBKrUumHwkXPrh4gl3GpzMjS2o5YEc2CMe 0JQvu0N+8qNFQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRKl-33Fx; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 06/38] docs: admin-guide: abi: add SPDX tags to ABI files Date: Tue, 28 Jan 2025 01:05:55 +0100 Message-ID: <28d86883d0e7f1de70c9e83eadec9e135abbd0d8.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Such files are missing SPDX tags containing the licensing information. Add them. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/admin-guide/abi-obsolete.rst | 2 ++ Documentation/admin-guide/abi-removed.rst | 2 ++ Documentation/admin-guide/abi-stable.rst | 2 ++ Documentation/admin-guide/abi-testing.rst | 2 ++ Documentation/admin-guide/abi.rst | 2 ++ 5 files changed, 10 insertions(+) diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/adm= in-guide/abi-obsolete.rst index 594e697aa1b2..b655615917f1 100644 --- a/Documentation/admin-guide/abi-obsolete.rst +++ b/Documentation/admin-guide/abi-obsolete.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ABI obsolete symbols =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admi= n-guide/abi-removed.rst index f9e000c81828..ba941c1af178 100644 --- a/Documentation/admin-guide/abi-removed.rst +++ b/Documentation/admin-guide/abi-removed.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ABI removed symbols =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin= -guide/abi-stable.rst index fc3361d847b1..5d738f345333 100644 --- a/Documentation/admin-guide/abi-stable.rst +++ b/Documentation/admin-guide/abi-stable.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ABI stable symbols =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admi= n-guide/abi-testing.rst index 19767926b344..a867e6578bf7 100644 --- a/Documentation/admin-guide/abi-testing.rst +++ b/Documentation/admin-guide/abi-testing.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ABI testing symbols =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/Documentation/admin-guide/abi.rst b/Documentation/admin-guide/= abi.rst index bcab3ef2597c..64e772bde943 100644 --- a/Documentation/admin-guide/abi.rst +++ b/Documentation/admin-guide/abi.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Linux ABI description =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 8AE514A1A; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; cv=none; b=P/V/SxzjfcqBkqndGS3yZe65lHb7fTA4NfyRX+DvV7o5TxZHUArarD1Kk5s3Ghb1ZH8AP34zajJk1zviRy0/0ibHzYQGGVJcA+9PjSrPH8DCA/wr+VmsnW7BS3F1IYOxrd25HBOPdF8OA4XsQCkfSoZxPdG+OI+6g0weiFtblj8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; c=relaxed/simple; bh=hdD/lkpi+9/YArLnX7wjSWSXiDV5h4tehxtqm9TMWBI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Kan5lc2QVJyMEwePFGGV9FqIqiuCNZd4L64XvOVlv1GyZWasucSrxyFVvxOxqk3+2+F88b5QJO044+TadYVKGmSC0g5BG0x8gApm7qcllzPE2FX6PS+hCHaWsCbPYhHOoBpXPPmhaKONu/qYTUPXToDKOehKtVZ0fxemm9OR+gE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=lPcaNiVu; 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="lPcaNiVu" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A9065C4AF09; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=hdD/lkpi+9/YArLnX7wjSWSXiDV5h4tehxtqm9TMWBI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=lPcaNiVudyKvkajoNLTbetl2NxriGbZ2iRUKGs44UrJeVO6SZ3LpwQxS09VqVZ37P PLZFUiiYjzVHts5nrQXw6PjdhSDKIrr5MtoZssbBCDBTax7K5CS295vwV2UwNw/8Xc CrQgpG2td/P7F6/jUqr/ZLybtnfWfyQlUAIuIBBJOSxfvUU7HrnuPqZhdQ3hRTiIho vH77g31jW7ZjebRJvaqaOTMX+Is4p2afS92NfOzTxL+cNCsoMyoCKMsN3Fp8e8xVR1 uwRYypRb/lbN+/0Axwehly9LTxEjqY1eiW9DnQQTGUqr0Yi+z6PqKZQvO30iYzM39y MIOq57D99Bvug== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRKp-3AM8; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , Johannes Berg , linux-kernel@vger.kernel.org, linux-wireless@vger.kernel.org Subject: [RFC v2 07/38] ABI: sysfs-class-rfkill: fix kernelversion tags Date: Tue, 28 Jan 2025 01:05:56 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Some kernelversion tags are missing colons. Add them to comply with ABI description and produce right results when converted to html/pdf. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/ABI/removed/sysfs-class-rfkill | 2 +- Documentation/ABI/stable/sysfs-class-rfkill | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Documentation/ABI/removed/sysfs-class-rfkill b/Documentation/A= BI/removed/sysfs-class-rfkill index f25174eafd55..20cb688af173 100644 --- a/Documentation/ABI/removed/sysfs-class-rfkill +++ b/Documentation/ABI/removed/sysfs-class-rfkill @@ -4,7 +4,7 @@ For details to this subsystem look at Documentation/driver-= api/rfkill.rst. =20 What: /sys/class/rfkill/rfkill[0-9]+/claim Date: 09-Jul-2007 -KernelVersion v2.6.22 +KernelVersion: v2.6.22 Contact: linux-wireless@vger.kernel.org Description: This file was deprecated because there no longer was a way to claim just control over a single rfkill instance. diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/AB= I/stable/sysfs-class-rfkill index 037979f7dc4b..67b605e3dd16 100644 --- a/Documentation/ABI/stable/sysfs-class-rfkill +++ b/Documentation/ABI/stable/sysfs-class-rfkill @@ -16,7 +16,7 @@ Description: The rfkill class subsystem folder. =20 What: /sys/class/rfkill/rfkill[0-9]+/name Date: 09-Jul-2007 -KernelVersion v2.6.22 +KernelVersion: v2.6.22 Contact: linux-wireless@vger.kernel.org Description: Name assigned by driver to this key (interface or driver nam= e). Values: arbitrary string. @@ -24,7 +24,7 @@ Values: arbitrary string. =20 What: /sys/class/rfkill/rfkill[0-9]+/type Date: 09-Jul-2007 -KernelVersion v2.6.22 +KernelVersion: v2.6.22 Contact: linux-wireless@vger.kernel.org Description: Driver type string ("wlan", "bluetooth", etc). Values: See include/linux/rfkill.h. @@ -32,7 +32,7 @@ Values: See include/linux/rfkill.h. =20 What: /sys/class/rfkill/rfkill[0-9]+/persistent Date: 09-Jul-2007 -KernelVersion v2.6.22 +KernelVersion: v2.6.22 Contact: linux-wireless@vger.kernel.org Description: Whether the soft blocked state is initialised from non-volat= ile storage at startup. @@ -44,7 +44,7 @@ Values: A numeric value: =20 What: /sys/class/rfkill/rfkill[0-9]+/state Date: 09-Jul-2007 -KernelVersion v2.6.22 +KernelVersion: v2.6.22 Contact: linux-wireless@vger.kernel.org Description: Current state of the transmitter. This file was scheduled to be removed in 2014, but due to its @@ -67,7 +67,7 @@ Values: A numeric value. =20 What: /sys/class/rfkill/rfkill[0-9]+/hard Date: 12-March-2010 -KernelVersion v2.6.34 +KernelVersion: v2.6.34 Contact: linux-wireless@vger.kernel.org Description: Current hardblock state. This file is read only. Values: A numeric value. @@ -81,7 +81,7 @@ Values: A numeric value. =20 What: /sys/class/rfkill/rfkill[0-9]+/soft Date: 12-March-2010 -KernelVersion v2.6.34 +KernelVersion: v2.6.34 Contact: linux-wireless@vger.kernel.org Description: Current softblock state. This file is read and write. Values: A numeric value. --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 84C113B7A8; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=l26PTqa2lKTo4R1asW3kmQ781qhiUB9njuqnSibg9TZwhqPyCF/F7Dq9RNWRcwlamOPUJArEtmBa2x7La4Ekg2AiMG/TuvFIc3NwecHHIKvtxiBDVfZwhKv68PXf6UdoM8CA13XEbzTKk96opDH0iipQ7BgZ+pkKLuux/h6Rdts= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=qrdsVxvuQlrneXqnvXiP9gvzFSX4e5M789thOkYc44o=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=S176/HAsfmW1KEGnl+oZ82hCmgez5AlzUZ+4vYy5Q3zB+PDTHkZA4q+7qHSk0Hdz4xGUjgrE41UKVIMbqEgZlR0e7SOJZf4IJsOq1l5tYfX4G/wJw+wlthYK1w2hhTIB7gdQx0NZDM3rfvCR0/LjBJHBWrFvemV6xx1L6sh6nzY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=E6ab7dgP; 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="E6ab7dgP" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BE42DC4AF0D; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=qrdsVxvuQlrneXqnvXiP9gvzFSX4e5M789thOkYc44o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=E6ab7dgPdEkdPhJvyCKS/9E0EO5F8n/dZLL5FLQtXs3yNaRXzd6PtyxJ628Ft3v8G 9HedX7jKOojmtq7FW6pUythdoOGPIDPhCyya5glDhU2gn0ldMxGjz4Y6+GG4QB1ZCU J/OvGIoUPHZmH4siVTOk2Q5WUuW1acX6Y1KQwuKBw2s4IvbcZVupt1QTC/MnrvedPK h1yWvgWI2WMF+qGBVM+e3xX1YWsa/qErnGrkqw53CSROrm9jfYlzKeooXXVOGn49sI +7hWdgmBi6DTXhv3U7jyBTJOPKmvH9hiOHHQcM5Bls1JojmUbcvJYOc6PZe5FmconD vXY33fUwgbDeA== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRKt-3HkN; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , James Clark , Mike Leach , Suzuki K Poulose , coresight@lists.linaro.org, linux-arm-kernel@lists.infradead.org, linux-kernel@vger.kernel.org Subject: [RFC v2 08/38] ABI: sysfs-bus-coresight-*: fix kernelversion tags Date: Tue, 28 Jan 2025 01:05:57 +0100 Message-ID: <33c5ec07012f1c05e3fd1df26d0f7422249571b5.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Some kernelversion tags are missing colons. Add them to comply with ABI description and produce right results when converted to html/pdf. Signed-off-by: Mauro Carvalho Chehab Acked-by: Suzuki K Poulose Reported-by: Akira Yokosawa --- .../testing/sysfs-bus-coresight-devices-cti | 78 +++++++++---------- .../testing/sysfs-bus-coresight-devices-tpdm | 52 ++++++------- 2 files changed, 65 insertions(+), 65 deletions(-) diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti b/Do= cumentation/ABI/testing/sysfs-bus-coresight-devices-cti index bf2869c413e7..a97b70f588da 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti @@ -1,241 +1,241 @@ What: /sys/bus/coresight/devices//enable Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (RW) Enable/Disable the CTI hardware. =20 What: /sys/bus/coresight/devices//powered Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) Indicate if the CTI hardware is powered. =20 What: /sys/bus/coresight/devices//ctmid Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) Display the associated CTM ID =20 What: /sys/bus/coresight/devices//nr_trigger_cons Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) Number of devices connected to triggers on this CTI =20 What: /sys/bus/coresight/devices//triggers/name Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) Name of connected device =20 What: /sys/bus/coresight/devices//triggers/in_signals Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) Input trigger signals from connected device =20 What: /sys/bus/coresight/devices//triggers/in_types Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) Functional types for the input trigger signals from connected device =20 What: /sys/bus/coresight/devices//triggers/out_signals Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) Output trigger signals to connected device =20 What: /sys/bus/coresight/devices//triggers/out_types Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) Functional types for the output trigger signals to connected device =20 What: /sys/bus/coresight/devices//regs/inout_sel Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (RW) Select the index for inen and outen registers. =20 What: /sys/bus/coresight/devices//regs/inen Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (RW) Read or write the CTIINEN register selected by inout_sel. =20 What: /sys/bus/coresight/devices//regs/outen Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (RW) Read or write the CTIOUTEN register selected by inout_se= l. =20 What: /sys/bus/coresight/devices//regs/gate Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (RW) Read or write CTIGATE register. =20 What: /sys/bus/coresight/devices//regs/asicctl Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (RW) Read or write ASICCTL register. =20 What: /sys/bus/coresight/devices//regs/intack Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Write) Write the INTACK register. =20 What: /sys/bus/coresight/devices//regs/appset Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (RW) Set CTIAPPSET register to activate channel. Read back to determine current value of register. =20 What: /sys/bus/coresight/devices//regs/appclear Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Write) Write APPCLEAR register to deactivate channel. =20 What: /sys/bus/coresight/devices//regs/apppulse Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Write) Write APPPULSE to pulse a channel active for one clock cycle. =20 What: /sys/bus/coresight/devices//regs/chinstatus Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) Read current status of channel inputs. =20 What: /sys/bus/coresight/devices//regs/choutstatus Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) read current status of channel outputs. =20 What: /sys/bus/coresight/devices//regs/triginstatus Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) read current status of input trigger signals =20 What: /sys/bus/coresight/devices//regs/trigoutstatus Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) read current status of output trigger signals. =20 What: /sys/bus/coresight/devices//channels/trigin_attach Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Write) Attach a CTI input trigger to a CTM channel. =20 What: /sys/bus/coresight/devices//channels/trigin_detach Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Write) Detach a CTI input trigger from a CTM channel. =20 What: /sys/bus/coresight/devices//channels/trigout_attach Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Write) Attach a CTI output trigger to a CTM channel. =20 What: /sys/bus/coresight/devices//channels/trigout_detach Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Write) Detach a CTI output trigger from a CTM channel. =20 What: /sys/bus/coresight/devices//channels/chan_gate_enable Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (RW) Enable CTIGATE for single channel (Write) or list enabled channels through the gate (R). =20 What: /sys/bus/coresight/devices//channels/chan_gate_disable Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Write) Disable CTIGATE for single channel. =20 What: /sys/bus/coresight/devices//channels/chan_set Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Write) Activate a single channel. =20 What: /sys/bus/coresight/devices//channels/chan_clear Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Write) Deactivate a single channel. =20 What: /sys/bus/coresight/devices//channels/chan_pulse Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Write) Pulse a single channel - activate for a single clock = cycle. =20 What: /sys/bus/coresight/devices//channels/trigout_filtered Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) List of output triggers filtered across all connection= s. =20 What: /sys/bus/coresight/devices//channels/trig_filter_enable Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (RW) Enable or disable trigger output signal filtering. =20 What: /sys/bus/coresight/devices//channels/chan_inuse Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) show channels with at least one attached trigger signa= l. =20 What: /sys/bus/coresight/devices//channels/chan_free Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) show channels with no attached trigger signals. =20 What: /sys/bus/coresight/devices//channels/chan_xtrigs_sel Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (RW) Write channel number to select a channel to view, read to see selected channel number. =20 What: /sys/bus/coresight/devices//channels/chan_xtrigs_in Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) Read to see input triggers connected to selected view channel. =20 What: /sys/bus/coresight/devices//channels/chan_xtrigs_out Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Read) Read to see output triggers connected to selected view channel. =20 What: /sys/bus/coresight/devices//channels/chan_xtrigs_reset Date: March 2020 -KernelVersion 5.7 +KernelVersion: 5.7 Contact: Mike Leach or Mathieu Poirier Description: (Write) Clear all channel / trigger programming. diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm b/D= ocumentation/ABI/testing/sysfs-bus-coresight-devices-tpdm index bf710ea6e0ef..53cb454b60d0 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm @@ -1,6 +1,6 @@ What: /sys/bus/coresight/devices//integration_test Date: January 2023 -KernelVersion 6.2 +KernelVersion: 6.2 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (Write) Run integration test for tpdm. Integration test @@ -14,7 +14,7 @@ Description: =20 What: /sys/bus/coresight/devices//reset_dataset Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (Write) Reset the dataset of the tpdm. @@ -24,7 +24,7 @@ Description: =20 What: /sys/bus/coresight/devices//dsb_trig_type Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the trigger type of the DSB for tpdm. @@ -35,7 +35,7 @@ Description: =20 What: /sys/bus/coresight/devices//dsb_trig_ts Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the trigger timestamp of the DSB for tpdm. @@ -46,7 +46,7 @@ Description: =20 What: /sys/bus/coresight/devices//dsb_mode Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the programming mode of the DSB for tpdm. @@ -60,7 +60,7 @@ Description: =20 What: /sys/bus/coresight/devices//dsb_edge/ctrl_idx Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the index number of the edge detection for the DSB @@ -69,7 +69,7 @@ Description: =20 What: /sys/bus/coresight/devices//dsb_edge/ctrl_val Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: Write a data to control the edge detection corresponding to @@ -85,7 +85,7 @@ Description: =20 What: /sys/bus/coresight/devices//dsb_edge/ctrl_mask Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: Write a data to mask the edge detection corresponding to the index @@ -97,21 +97,21 @@ Description: =20 What: /sys/bus/coresight/devices//dsb_edge/edcr[0:15] Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: Read a set of the edge control value of the DSB in TPDM. =20 What: /sys/bus/coresight/devices//dsb_edge/edcmr[0:7] Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: Read a set of the edge control mask of the DSB in TPDM. =20 What: /sys/bus/coresight/devices//dsb_trig_patt/xpr[0:7] Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the value of the trigger pattern for the DSB @@ -119,7 +119,7 @@ Description: =20 What: /sys/bus/coresight/devices//dsb_trig_patt/xpmr[0:7] Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the mask of the trigger pattern for the DSB @@ -127,21 +127,21 @@ Description: =20 What: /sys/bus/coresight/devices//dsb_patt/tpr[0:7] Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the value of the pattern for the DSB subunit TPDM. =20 What: /sys/bus/coresight/devices//dsb_patt/tpmr[0:7] Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the mask of the pattern for the DSB subunit TPDM. =20 What: /sys/bus/coresight/devices//dsb_patt/enable_ts Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (Write) Set the pattern timestamp of DSB tpdm. Read @@ -153,7 +153,7 @@ Description: =20 What: /sys/bus/coresight/devices//dsb_patt/set_type Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (Write) Set the pattern type of DSB tpdm. Read @@ -165,7 +165,7 @@ Description: =20 What: /sys/bus/coresight/devices//dsb_msr/msr[0:31] Date: March 2023 -KernelVersion 6.7 +KernelVersion: 6.7 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the MSR(mux select register) for the DSB subunit @@ -173,7 +173,7 @@ Description: =20 What: /sys/bus/coresight/devices//cmb_mode Date: January 2024 -KernelVersion 6.9 +KernelVersion: 6.9 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (Write) Set the data collection mode of CMB tpdm. Continuous change creates CMB data set elements on every CMBCLK edge. @@ -187,7 +187,7 @@ Description: (Write) Set the data collection mode of CM= B tpdm. Continuous =20 What: /sys/bus/coresight/devices//cmb_trig_patt/xpr[0:1] Date: January 2024 -KernelVersion 6.9 +KernelVersion: 6.9 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the value of the trigger pattern for the CMB @@ -195,7 +195,7 @@ Description: =20 What: /sys/bus/coresight/devices//cmb_trig_patt/xpmr[0:1] Date: January 2024 -KernelVersion 6.9 +KernelVersion: 6.9 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the mask of the trigger pattern for the CMB @@ -203,21 +203,21 @@ Description: =20 What: /sys/bus/coresight/devices//dsb_patt/tpr[0:1] Date: January 2024 -KernelVersion 6.9 +KernelVersion: 6.9 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the value of the pattern for the CMB subunit TPDM. =20 What: /sys/bus/coresight/devices//dsb_patt/tpmr[0:1] Date: January 2024 -KernelVersion 6.9 +KernelVersion: 6.9 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the mask of the pattern for the CMB subunit TPDM. =20 What: /sys/bus/coresight/devices//cmb_patt/enable_ts Date: January 2024 -KernelVersion 6.9 +KernelVersion: 6.9 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (Write) Set the pattern timestamp of CMB tpdm. Read @@ -229,7 +229,7 @@ Description: =20 What: /sys/bus/coresight/devices//cmb_trig_ts Date: January 2024 -KernelVersion 6.9 +KernelVersion: 6.9 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the trigger timestamp of the CMB for tpdm. @@ -240,7 +240,7 @@ Description: =20 What: /sys/bus/coresight/devices//cmb_ts_all Date: January 2024 -KernelVersion 6.9 +KernelVersion: 6.9 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Read or write the status of timestamp upon all interface. @@ -252,7 +252,7 @@ Description: =20 What: /sys/bus/coresight/devices//cmb_msr/msr[0:31] Date: January 2024 -KernelVersion 6.9 +KernelVersion: 6.9 Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) <= quic_taozha@quicinc.com> Description: (RW) Set/Get the MSR(mux select register) for the CMB subunit --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 BF4E68F54; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; cv=none; b=AJLBPUnLwee/ZFmc4I27ny7tazJiYof+ZftmUd/c5hlqiX4cteH56NlbGBt56tKiBGj66+7C9nqikstjwvqWMGAb8E7xYs3sn2CFYFTE1er12fBxr4b2vMHIU+nHP9eCTyyuChywBf2HMJDw8QAasDiK0ioLVqmSWapks4xr+FQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; c=relaxed/simple; bh=erz4OcTOvbnxgyfwrQKNDa0AznbtN3e8j1C5SQqASZI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=pL1FORstiGucI4rJLRuNzwbh2YalawBp+442p8J1PsQVtzHU5+7DPDDNuFtv6scCxNSK7sFxBzX4OzMlmHLYxrJz1sU9bszd6TZmwJuzmfA0GmUE1Ymsb1ZfJa8d2zEkBgJMOhHJJMPG6Kq9bE/gYuEPTuWlHL7oWInEQ3Ddx1I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=TntjJdWI; 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="TntjJdWI" Received: by smtp.kernel.org (Postfix) with ESMTPSA id AE5B9C4CEEA; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=erz4OcTOvbnxgyfwrQKNDa0AznbtN3e8j1C5SQqASZI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=TntjJdWINE6c/nABfb/8Q9nhNMMR9l7sgFIx74N2eAXtt/m8Lw9T1vGnky0oCn0ic FWtpq4cWerB1Z7UUepgCnQr2qIA8me/f7CxTZmbDkfSe1OuKkxGufdmJNEZ+MyrJwo 1rTJEcTXTkdSAEVE9mxNd/XV+fqr1mo11+E5X95VEuzS0AHyXnLnZ/f7YPv7nvhp3V YQGWiNyJ+KhPaa0bjr3rLJY3/DwlNafByi0AVFIbqzQ0HP5gV+vQKPBdIIOWXxfkBF JSp0YUEZXcfhtX37FsLeSRg4VdRg+VbHnQNomqcY1MU64nzhyrErikVpmb2HrFJCVy 2sYviSwNffDdw== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRKx-3P8K; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 09/38] ABI: sysfs-driver-dma-idxd: fix date tags Date: Tue, 28 Jan 2025 01:05:58 +0100 Message-ID: <08b4790d10620afda947814e1a4db744595b9b2f.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Some date tags are missing colons. Add them to comply with ABI description and produce right results when converted to html/pdf. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/ABI/stable/sysfs-driver-dma-idxd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/ABI/stable/sysfs-driver-dma-idxd b/Documentation= /ABI/stable/sysfs-driver-dma-idxd index f2ec42949a54..4a355e6747ae 100644 --- a/Documentation/ABI/stable/sysfs-driver-dma-idxd +++ b/Documentation/ABI/stable/sysfs-driver-dma-idxd @@ -246,14 +246,14 @@ Description: Controls whether PRS disable is turned o= n for the workqueue. capability. =20 What: /sys/bus/dsa/devices/wq./occupancy -Date May 25, 2021 +Date: May 25, 2021 KernelVersion: 5.14.0 Contact: dmaengine@vger.kernel.org Description: Show the current number of entries in this WQ if WQ Occupancy Support bit WQ capabilities is 1. =20 What: /sys/bus/dsa/devices/wq./enqcmds_retries -Date Oct 29, 2021 +Date: Oct 29, 2021 KernelVersion: 5.17.0 Contact: dmaengine@vger.kernel.org Description: Indicate the number of retires for an enqcmds submission on a= sharedwq. --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 6383533F3; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; cv=none; b=hiWekdC5b9twYiLXVICHYCPk7BM8/z225P7Ut2Ro07d3g2KuPut5Mh5L4rhkZA7k//7IoFdR+ILKzxqwByiVNPAbXxPTEsGXKyZlwbDWSufPLEPtBp4cyllo0hZ+WDUaNBFHBczQ18CXXD7hq9AUzsgE2RNBSxJpvkoVObKjKKs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; c=relaxed/simple; bh=LI59JQtyPV/HF12ShAdqHJX2HFF3NXc8/5bk+IONPNM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=DHkP9L/Pzf8Z/snyllA2pT6KpqJuvihVZq4ZYS2MWGuR5mgrppC3Vp5UpF/fqtPauergZN4E08g4R662eP5DBhPbr78LOxySbzljyFLq+EnJJsB0DXB8j7GPKpI/5yLPsLALg09YjGXCpXnEqcWcokYbX2WBiB91geQH8Vm8SVs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=UMbqCVZI; 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="UMbqCVZI" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 995C3C4CEE0; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=LI59JQtyPV/HF12ShAdqHJX2HFF3NXc8/5bk+IONPNM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=UMbqCVZIhWUNOG6pwcxM3vV7QS3gmeUlDvAxwudM+XQlG18DYaJVCyQfHG5/8K/yj 0GIssh6oORjjGHMP0vHmL8V8C1dvZIJvso/5PAJnnz3DGfuHKbrZ4EWK3Mb4j3lFFq GgUMPEszGBPpDJBXf7Y2jcHEyK6n8qL4hFO8oULBLoDgb6Wgqa9CkQfcDPLLItwBO1 M4JSK2yrdbsqGO7qA35AMAWhnBoC2/YEB11g7SAxmxwQJTBid96VAp/cz5Xpj3ur/q cl2HpIegxB09n0IdEuR3u1C8kVPcwJDYdLcyGrYd9dWUXNGeIkDOhqc/mlxUIU37Ez SM0mJMidSzbdg== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRL1-3WAU; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , Chao Yu , Jaegeuk Kim , linux-f2fs-devel@lists.sourceforge.net, linux-kernel@vger.kernel.org Subject: [RFC v2 10/38] ABI: sysfs-fs-f2fs: fix date tags Date: Tue, 28 Jan 2025 01:05:59 +0100 Message-ID: <380e21e11e5b1b9e7cc38ddb0c1e6695b3c69254.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Some date tags are missing colons. Add them to comply with ABI description and produce right results when converted to html/pdf. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/ABI/testing/sysfs-fs-f2fs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/te= sting/sysfs-fs-f2fs index 3e1630c70d8a..e44bb614964b 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -347,7 +347,7 @@ Description: Used to control configure extension list: - [c] means add/del cold file extension =20 What: /sys/fs/f2fs//unusable -Date April 2019 +Date: April 2019 Contact: "Daniel Rosenberg" Description: If checkpoint=3Ddisable, it displays the number of blocks that are unusable. @@ -355,7 +355,7 @@ Description: If checkpoint=3Ddisable, it displays the n= umber of blocks that would be unusable if checkpoint=3Ddisable were to be set. =20 What: /sys/fs/f2fs//encoding -Date July 2019 +Date: July 2019 Contact: "Daniel Rosenberg" Description: Displays name and version of the encoding set for the filesys= tem. If no encoding is set, displays (none) --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 BEFDD8BEA; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; cv=none; b=PbfaAnZ7taCKh+oatX5fIDFMbrcqp7A1LrDMTuNgmWkXty7JCbjmMmk6LjXqLsjuJUQqQqrpyZd4p2IfkmGBBeK7Fusfb+Dh0Dxdu3/OJ7yZYvH0c9ZsiiwTdLyIlQE1BuQZuNEkEWF9pffSZN+qGMuxGGqXFMtnOFoljsV3kXo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; c=relaxed/simple; bh=Tj1nz2RZBql0geo5lraeHUCDCc6IdX7LSdJsN5wj1mY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Qbz4l0MPdoRNtKmog/83sfsZ03iIsxOAZEm6JuJDaXjjfYn24QA8GRZr4AbGnoV1UbH2ebJW3KmPjj/yX3am86jzB1B+zzPWegEJt01PKSXAkrUkVAGxaTxspQvx2uRph9SBg1R9qHdIUYaIZ4zSEbbotvngfIJOAzrd9CGnCKw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Y4ZHg6+t; 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="Y4ZHg6+t" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B41DCC4CEEC; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=Tj1nz2RZBql0geo5lraeHUCDCc6IdX7LSdJsN5wj1mY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Y4ZHg6+t5NgU4UAHHiPaxTzU0WBl145Am6lLM2yyq1wq3GpqJ/k6+Dz6DOqkbv6gR 9gkLbYQ1/d29lI70OOXjRe6cjr3tuCmWiaXUZVEAX0Pga48uLsMq0z09VklcnOFB6a 2x6Ai4YcKcL41rWQ/gTY5Y3oo6Y0pYuDtHhC11Ji0MRGffCrn1CcEDuWHANmsIk4du bLkn6BKHGuCUMKdSvjPWg7g0qcO2UpWEQijicNUwc3TZtcp/Biq7GrxEZkLNL9IBrQ hdM/a+FqhZ6bbDI/e0j+X8yDCbnwqOYrnSMI+7KsWNJ8O3SM4oUSGXQjI60EsU2lFF KgnPPcmOx9MWg== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRL5-3d6t; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 11/38] ABI: sysfs-power: fix a what tag Date: Tue, 28 Jan 2025 01:06:00 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" There is one What tag that it is using semicolon instead of colon. Fix it to comply with ABI description and produce right results when converted to html/pdf. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/ABI/testing/sysfs-power | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/test= ing/sysfs-power index a3942b1036e2..2192478e83cf 100644 --- a/Documentation/ABI/testing/sysfs-power +++ b/Documentation/ABI/testing/sysfs-power @@ -131,7 +131,7 @@ Description: CAUTION: Using it will cause your machine's real-time (CMOS) clock to be set to a random invalid time after a resume. =20 -What; /sys/power/pm_trace_dev_match +What: /sys/power/pm_trace_dev_match Date: October 2010 Contact: James Hogan Description: --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 A8E2325A63E; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; cv=none; b=M3bkTkmTmLPhKhX5+1SBsJzKvNbKe/reLO0m4sN8TX7H5Jj2upnj7r5tmosHIeMW+PbBzBvLf63k0IhC3Y0VDnpZ3vXFDQNafdRXQ1mtZYjHba4eLw7DWoybbZdiXYUTQazFm5TYuANfUHKH3nbyNXbUV0VHzgQDMXI0UTDQqQ4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; c=relaxed/simple; bh=0f7tLKTuX4jKgrpwqlZrJAjeosOKAdyvIyBElssJbRg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=iTgazBn40LK0I1uxbjn/pnyYtbwtSetJdCcjA+v1k5THT9NSJEV+Io2OnIK+Hj7de42q3kZ9dQ95aWEKmBvukMtr+CGFUMjDMNaeleMi8Uey9E0Qpccz6MMq7nGT194U5aIz/KyHw5wKmx09+RUzSiwmBbw0YVcDs7D5J/ITKrg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Frsp8NPL; 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="Frsp8NPL" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BBF03C4AF0B; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=0f7tLKTuX4jKgrpwqlZrJAjeosOKAdyvIyBElssJbRg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Frsp8NPL/mhQlbpT75V/1pHNOi0E8xaFgfwEu0FwigoJeNBJEEmZiuYxibq1m0lYW gjOzOyg+jco7OTYIy1wpXpvPjO4wNsM6EYZKQdOnOnoEQUWATxxIO9Ku1b9eAc7SR5 ZR2F9CLAB4ASBxu+exkzFlrgAbCbAAxBk+Hi8u/oiow3Vw1mZ182AdZL4Z1R1O4F1s juvHJaZpFGa2650Lb7/XXKZ2oG6jiEjUGwSvgXuMx8Y+rg7OZoJMhH3HrMCq3RgwVr q052u2dYL6l0DntMhEyHiSX0burOZnrQkD6Kmv+kqlG+hPCgh+kjnyI6nIt/DRWbcB GlOTwB5h7jR+A== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRL9-3jvf; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 12/38] scripts/documentation-file-ref-check: don't check perl/python scripts Date: Tue, 28 Jan 2025 01:06:01 +0100 Message-ID: <1d4edb4d2f5751b86f205785045cec7e9bc75a42.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Such scripts may have regular expressions, which would make the parser confusing. Also, they shouldn't hardcode filenames there, so skipping them is OK. While here, also don't check references on extensions used for file backup and patch rej/orig. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- scripts/documentation-file-ref-check | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-f= ile-ref-check index 68083f2f1122..408b1dbe7884 100755 --- a/scripts/documentation-file-ref-check +++ b/scripts/documentation-file-ref-check @@ -92,7 +92,7 @@ while () { next if ($f =3D~ m,^Next/,); =20 # Makefiles and scripts contain nasty expressions to parse docs - next if ($f =3D~ m/Makefile/ || $f =3D~ m/\.sh$/); + next if ($f =3D~ m/Makefile/ || $f =3D~ m/\.(sh|py|pl|~|rej|org|orig)$/); =20 # It doesn't make sense to parse hidden files next if ($f =3D~ m#/\.#); --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 4BED426ACD; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=VFkM6/GEBOdvU2WvGwau3OoigNqZN+KiQv19XormVxAZ5xuUooudpA1bAzEjXqWX+hukZFilLJKIcOD2sAOvVMIs3fWOnBV2H0FvhtftAZpkbY94Cr0KWtrigw38bYdv5NnxpUweTVmvt2OFDnqQUoDKPFxtRgQx84Ft5IK3W4k= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=AgS5F8kjI7ZZkxFf+z9fZP2YXAdsS71+uVqNN+FA0rQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=sHr7/GuAxO90EuIJuXKP5T86EaYNKYBqIJ9oqxPnoDft9a4zFnxbppXQYQNPkRDROCw/zIG9dJPjPpfaQ2lUnvw5c/BUPPg2v47EfnZqqRpF+3/YsrssPy/NGh/ssIVdW6t0lMomX2ZrIMJfGsy6jDe8pbnfzwjD2ahuw3Hgsh4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=m7gaDgI7; 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="m7gaDgI7" Received: by smtp.kernel.org (Postfix) with ESMTPSA id CA98EC4CEF2; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=AgS5F8kjI7ZZkxFf+z9fZP2YXAdsS71+uVqNN+FA0rQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=m7gaDgI7WckZXO7OicjuvldnhOrZ+fI+86isfZBFcmjOJ1cSP8oI33UicZeASAV5A I+1z0gmDnZxh2+Od/7/GXhL5XBxfAs5REICkHftsFjspTImCfxhWN0LACDUNdkHc0t KA153pKCs2Yx+Nx9MrNIqyzcmYb5g56cncW7GXJ2qFqNKwzbO9khAKGtBBLMdk+WRA xHA4ciI19JIXB2n5tBZH4GQU4hQBJMtEkVg+Zb6EUbF9ShmXXg1cM8w6DwhWdZlrcy IIE0cujzve0S1ktebiLK4X+xL6OgP2E8LlenAJqS13VGYPeeqhV+0S/yqS49laMwrp 0OzHk5rlR5DpA== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRLD-3r9Z; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 13/38] scripts/get_abi.py: add a Python tool to generate ReST output Date: Tue, 28 Jan 2025 01:06:02 +0100 Message-ID: <2a4677216ac2ad766c3a6112691eac5f4b77680a.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" The get_abi.pl script is requiring some care, but it seems that the number of changes on it since when I originally wrote it was not too high. Maintaining perl scripts without using classes requires a higher efforted than on python, due to global variables management. Also, it sounds easier to find python developer those days than perl ones. As a plus, using a Python class to handle ABI allows a better integration with Sphinx extensions, allowing, for instance, to let automarkup to generate cross-references for ABI symbols. With that in mind, rewrite the core of get_abi.pl in Python, using classes, to help producing documentation. This will allow a better integration in the future with the Sphinx ABI extension. The algorithms used there are the same as the ones in Perl, with a couple of cleanups to remove redundant variables and to help with cross-reference generation. While doing that, remove some code that were important in the past, where ABI files weren't using ReST format. Some minor improvements were added like using a fixed seed when generating ABI keys for duplicated names, making its results reproductible. The end script is a little bit faster than the original one (tested on a machine with ssd disks). That's probably because we're now using only pre-compiled regular expressions, and it is using string replacement methods instead of regex where possible. The new version is a little bit more conservative when converting text to cross-references to avoid adding them into literal blocks. To ensure that the ReST output is parsing all variables and files properly, the end result was compared using diff with the one produced by the perl script and showed no regressions. There are minor improvements at the results, as it now properly groups What on some special cases. It also better escape some XREF names. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- scripts/get_abi.py | 619 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 619 insertions(+) create mode 100755 scripts/get_abi.py diff --git a/scripts/get_abi.py b/scripts/get_abi.py new file mode 100755 index 000000000000..0b5a10e76a3c --- /dev/null +++ b/scripts/get_abi.py @@ -0,0 +1,619 @@ +#!/usr/bin/env python3 +# pylint: disable=3DR0902,R0903,R0911,R0912,R0913,R0914,R0915,R0917,C0302 +# Copyright(c) 2025: Mauro Carvalho Chehab . +# SPDX-License-Identifier: GPL-2.0 + +""" +Parse ABI documentation and produce results from it. +""" + +import argparse +import logging +import os +import re +import sys + +from glob import glob +from pprint import pformat +from random import randrange, seed + +ABI_DIR =3D "Documentation/ABI/" + +# Debug levels +DEBUG_WHAT_PARSING =3D 1 +DEBUG_WHAT_OPEN =3D 2 +DEBUG_DUMP_ABI_STRUCTS =3D 4 + +DEBUG_HELP =3D """ +Print debug information according with the level(s), +which is given by the following bitmask: + +1 - enable debug parsing logic +2 - enable debug messages on file open +4 - enable debug for ABI parse data +""" + + +class AbiParser: + """Main class to parse ABI files""" + + TAGS =3D r"(what|where|date|kernelversion|contact|description|users)" + XREF =3D r"(?:^|\s|\()(\/(?:sys|config|proc|dev|kvd)\/[^,.:;\)\s]+)(?:= [,.:;\)\s]|\Z)" + + def __init__(self, directory, logger=3DNone, + enable_lineno=3DFalse, show_warnings=3DTrue, debug=3D0): + """Stores arguments for the class and initialize class vars""" + + self.directory =3D directory + self.enable_lineno =3D enable_lineno + self.show_warnings =3D show_warnings + self.debug =3D debug + + if not logger: + self.log =3D logging.getLogger("get_abi") + else: + self.log =3D logger + + self.data =3D {} + self.what_symbols =3D {} + self.file_refs =3D {} + self.what_refs =3D {} + + # Regular expressions used on parser + self.re_tag =3D re.compile(r"(\S+)(:\s*)(.*)", re.I) + self.re_valid =3D re.compile(self.TAGS) + self.re_start_spc =3D re.compile(r"(\s*)(\S.*)") + self.re_whitespace =3D re.compile(r"^\s+") + + # Regular used on print + self.re_what =3D re.compile(r"(\/?(?:[\w\-]+\/?){1,2})") + self.re_escape =3D re.compile(r"([\.\x01-\x08\x0e-\x1f\x21-\x2f\x3= a-\x40\x7b-\xff])") + self.re_unprintable =3D re.compile(r"([\x00-\x2f\x3a-\x40\x5b-\x60= \x7b-\xff]+)") + self.re_title_mark =3D re.compile(r"\n[\-\*\=3D\^\~]+\n") + self.re_doc =3D re.compile(r"Documentation/(?!devicetree)(\S+)\.rs= t") + self.re_abi =3D re.compile(r"(Documentation/ABI/)([\w\/\-]+)") + self.re_xref_node =3D re.compile(self.XREF) + + def warn(self, fdata, msg, extra=3DNone): + """Displays a parse error if warning is enabled""" + + if not self.show_warnings: + return + + msg =3D f"{fdata.fname}:{fdata.ln}: {msg}" + if extra: + msg +=3D "\n\t\t" + extra + + self.log.warning(msg) + + def add_symbol(self, what, fname, ln=3DNone, xref=3DNone): + """Create a reference table describing where each 'what' is locate= d""" + + if what not in self.what_symbols: + self.what_symbols[what] =3D {"file": {}} + + if fname not in self.what_symbols[what]["file"]: + self.what_symbols[what]["file"][fname] =3D [] + + if ln and ln not in self.what_symbols[what]["file"][fname]: + self.what_symbols[what]["file"][fname].append(ln) + + if xref: + self.what_symbols[what]["xref"] =3D xref + + def _parse_line(self, fdata, line): + """Parse a single line of an ABI file""" + + new_what =3D False + new_tag =3D False + content =3D None + + match =3D self.re_tag.match(line) + if match: + new =3D match.group(1).lower() + sep =3D match.group(2) + content =3D match.group(3) + + match =3D self.re_valid.search(new) + if match: + new_tag =3D match.group(1) + else: + if fdata.tag =3D=3D "description": + # New "tag" is actually part of description. + # Don't consider it a tag + new_tag =3D False + elif fdata.tag !=3D "": + self.warn(fdata, f"tag '{fdata.tag}' is invalid", line) + + if new_tag: + # "where" is Invalid, but was a common mistake. Warn if found + if new_tag =3D=3D "where": + self.warn(fdata, "tag 'Where' is invalid. Should be 'What:= ' instead") + new_tag =3D "what" + + if new_tag =3D=3D "what": + fdata.space =3D None + + if content not in self.what_symbols: + self.add_symbol(what=3Dcontent, fname=3Dfdata.fname, l= n=3Dfdata.ln) + + if fdata.tag =3D=3D "what": + fdata.what.append(content.strip("\n")) + else: + if fdata.key: + if "description" not in self.data.get(fdata.key, {= }): + self.warn(fdata, f"{fdata.key} doesn't have a = description") + + for w in fdata.what: + self.add_symbol(what=3Dw, fname=3Dfdata.fname, + ln=3Dfdata.what_ln, xref=3Dfda= ta.key) + + fdata.label =3D content + new_what =3D True + + key =3D "abi_" + content.lower() + fdata.key =3D self.re_unprintable.sub("_", key).strip(= "_") + + # Avoid duplicated keys but using a defined seed, to m= ake + # the namespace identical if there aren't changes at t= he + # ABI symbols + seed(42) + + while fdata.key in self.data: + char =3D randrange(0, 51) + ord("A") + if char > ord("Z"): + char +=3D ord("a") - ord("Z") - 1 + + fdata.key +=3D chr(char) + + if fdata.key and fdata.key not in self.data: + self.data[fdata.key] =3D { + "what": [content], + "file": [fdata.file_ref], + "line_no": fdata.ln, + } + + fdata.what =3D self.data[fdata.key]["what"] + + self.what_refs[content] =3D fdata.key + fdata.tag =3D new_tag + fdata.what_ln =3D fdata.ln + + if fdata.nametag["what"]: + t =3D (content, fdata.key) + if t not in fdata.nametag["symbols"]: + fdata.nametag["symbols"].append(t) + + return + + if fdata.tag and new_tag: + fdata.tag =3D new_tag + + if new_what: + fdata.label =3D "" + + self.data[fdata.key]["type"] =3D fdata.ftype + + if "description" in self.data[fdata.key]: + self.data[fdata.key]["description"] +=3D "\n\n" + + if fdata.file_ref not in self.data[fdata.key]["file"]: + self.data[fdata.key]["file"].append(fdata.file_ref) + + if self.debug =3D=3D DEBUG_WHAT_PARSING: + self.log.debug("what: %s", fdata.what) + + if not fdata.what: + self.warn(fdata, "'What:' should come first:", line) + return + + if new_tag =3D=3D "description": + fdata.space =3D None + + if content: + sep =3D sep.replace(":", " ") + + c =3D " " * len(new_tag) + sep + content + c =3D c.expandtabs() + + match =3D self.re_start_spc.match(c) + if match: + # Preserve initial spaces for the first line + fdata.space =3D match.group(1) + content =3D match.group(2) + "\n" + + self.data[fdata.key][fdata.tag] =3D content + + return + + # Store any contents before tags at the database + if not fdata.tag and "what" in fdata.nametag: + fdata.nametag["description"] +=3D line + return + + if fdata.tag =3D=3D "description": + content =3D line.expandtabs() + + if self.re_whitespace.sub("", content) =3D=3D "": + self.data[fdata.key][fdata.tag] +=3D "\n" + return + + if fdata.space is None: + match =3D self.re_start_spc.match(content) + if match: + # Preserve initial spaces for the first line + fdata.space =3D match.group(1) + + content =3D match.group(2) + "\n" + else: + if content.startswith(fdata.space): + content =3D content[len(fdata.space):] + + else: + fdata.space =3D "" + + if fdata.tag =3D=3D "what": + w =3D content.strip("\n") + if w: + self.data[fdata.key][fdata.tag].append(w) + else: + self.data[fdata.key][fdata.tag] +=3D content + return + + content =3D line.strip() + if fdata.tag: + if fdata.tag =3D=3D "what": + w =3D content.strip("\n") + if w: + self.data[fdata.key][fdata.tag].append(w) + else: + self.data[fdata.key][fdata.tag] +=3D "\n" + content.rstrip= ("\n") + return + + # Everything else is error + if content: + self.warn(fdata, "Unexpected content", line) + + def parse_file(self, fname, path, basename): + """Parse a single file""" + + ref =3D f"abi_file_{path}_{basename}" + ref =3D self.re_unprintable.sub("_", ref).strip("_") + + # Store per-file state into a namespace variable. This will be used + # by the per-line parser state machine and by the warning function. + fdata =3D argparse.Namespace + + fdata.fname =3D fname + fdata.name =3D basename + + pos =3D fname.find(ABI_DIR) + if pos > 0: + f =3D fname[pos:] + else: + f =3D fname + + fdata.file_ref =3D (f, ref) + self.file_refs[f] =3D ref + + fdata.ln =3D 0 + fdata.what_ln =3D 0 + fdata.tag =3D "" + fdata.label =3D "" + fdata.what =3D [] + fdata.key =3D None + fdata.xrefs =3D None + fdata.space =3D None + fdata.ftype =3D path.split("/")[0] + + fdata.nametag =3D {} + fdata.nametag["what"] =3D [f"File {path}/{basename}"] + fdata.nametag["type"] =3D "File" + fdata.nametag["file"] =3D [fdata.file_ref] + fdata.nametag["line_no"] =3D 1 + fdata.nametag["description"] =3D "" + fdata.nametag["symbols"] =3D [] + + self.data[ref] =3D fdata.nametag + + if self.debug & DEBUG_WHAT_OPEN: + self.log.debug("Opening file %s", fname) + + with open(fname, "r", encoding=3D"utf8", errors=3D"backslashreplac= e") as fp: + for line in fp: + fdata.ln +=3D 1 + + self._parse_line(fdata, line) + + if "description" in fdata.nametag: + fdata.nametag["description"] =3D fdata.nametag["descriptio= n"].lstrip("\n") + + if fdata.key: + if "description" not in self.data.get(fdata.key, {}): + self.warn(fdata, f"{fdata.key} doesn't have a descript= ion") + + for w in fdata.what: + self.add_symbol(what=3Dw, fname=3Dfname, xref=3Dfdata.= key) + + def parse_abi(self): + """Parse documentation ABI""" + + ignore_suffixes =3D ("rej", "org", "orig", "bak", "~") + re_abi =3D re.compile(r".*" + ABI_DIR) + + for fname in glob(os.path.join(self.directory, "**"), recursive=3D= True): + if os.path.isdir(fname): + continue + + basename =3D os.path.basename(fname) + + if basename =3D=3D "README": + continue + if basename.startswith(".") or basename.endswith(ignore_suffix= es): + continue + + path =3D re_abi.sub("", os.path.dirname(fname)) + + self.parse_file(fname, path, basename) + + if self.debug & DEBUG_DUMP_ABI_STRUCTS: + self.log.debug(pformat(self.data)) + + def print_desc_txt(self, desc): + """Print description as found inside ABI files""" + + desc =3D desc.strip(" \t\n") + + print(desc + "\n") + + def print_desc_rst(self, desc): + """Enrich ReST output by creating cross-references""" + + # Remove title markups from the description + # Having titles inside ABI files will only work if extra + # care would be taken in order to strictly follow the same + # level order for each markup. + desc =3D self.re_title_mark.sub("\n\n", "\n" + desc) + desc =3D desc.rstrip(" \t\n").lstrip("\n") + + + # FIXME: Python's regex performance for non-compiled expressions + # is a lot worse than Perl, as Perl automatically caches them at t= heir + # first usage. Here, we'll need to do the same, as otherwise the + # performance penalty is be high + + new_desc =3D "" + for d in desc.split("\n"): + if d =3D=3D "": + new_desc +=3D "\n" + continue + + # Use cross-references for doc files where needed + d =3D self.re_doc.sub(r":doc:`/\1`", d) + + # Use cross-references for ABI generated docs where needed + matches =3D self.re_abi.findall(d) + for m in matches: + abi =3D m[0] + m[1] + + xref =3D self.file_refs.get(abi) + if not xref: + # This may happen if ABI is on a separate directory, + # like parsing ABI testing and symbol is at stable. + # The proper solution is to move this part of the code + # for it to be inside sphinx/kernel_abi.py + self.log.info("Didn't find ABI reference for '%s'", ab= i) + else: + new =3D self.re_escape.sub(r"\\\1", m[1]) + d =3D re.sub(fr"\b{abi}\b", f":ref:`{new} <{xref}>`", = d) + + # Seek for cross reference symbols like /sys/... + # Need to be careful to avoid doing it on a code block + if d[0] not in [" ", "\t"]: + matches =3D self.re_xref_node.findall(d) + for m in matches: + # Finding ABI here is more complex due to wildcards + xref =3D self.what_refs.get(m) + if xref: + new =3D self.re_escape.sub(r"\\\1", m) + d =3D re.sub(fr"\b{m}\b", f":ref:`{new} <{xref}>`"= , d) + + new_desc +=3D d + "\n" + + print(new_desc + "\n") + + def print_data(self, enable_lineno, output_in_txt, show_file=3DFalse): + """Print ABI at stdout""" + + part =3D None + for key, v in sorted(self.data.items(), + key=3Dlambda x: (x[1].get("type", ""), + x[1].get("what"))): + + wtype =3D v.get("type", "Var") + file_ref =3D v.get("file") + names =3D v.get("what", [""]) + + if not show_file and wtype =3D=3D "File": + continue + + if enable_lineno: + ln =3D v.get("line_no", 1) + print(f".. LINENO {file_ref[0][0]}#{ln}\n") + + if wtype !=3D "File": + cur_part =3D names[0] + if cur_part.find("/") >=3D 0: + match =3D self.re_what.match(cur_part) + if match: + symbol =3D match.group(1).rstrip("/") + cur_part =3D "Symbols under " + symbol + + if cur_part and cur_part !=3D part: + part =3D cur_part + print(f"{part}\n{"-" * len(part)}\n") + + print(f".. _{key}:\n") + + max_len =3D 0 + for i in range(0, len(names)): # pylint: disable= =3DC0200 + names[i] =3D "**" + self.re_escape.sub(r"\\\1", names[= i]) + "**" + + max_len =3D max(max_len, len(names[i])) + + print("+-" + "-" * max_len + "-+") + for name in names: + print(f"| {name}" + " " * (max_len - len(name)) + " |") + print("+-" + "-" * max_len + "-+") + print() + + for ref in file_ref: + if wtype =3D=3D "File": + print(f".. _{ref[1]}:\n") + else: + base =3D os.path.basename(ref[0]) + print(f"Defined on file :ref:`{base} <{ref[1]}>`\n") + + if wtype =3D=3D "File": + print(f"{names[0]}\n{"-" * len(names[0])}\n") + + desc =3D v.get("description") + if not desc and wtype !=3D "File": + print(f"DESCRIPTION MISSING for {names[0]}\n") + + if desc: + if output_in_txt: + self.print_desc_txt(desc) + else: + self.print_desc_rst(desc) + + symbols =3D v.get("symbols") + if symbols: + print("Has the following ABI:\n") + + for w, label in symbols: + # Escape special chars from content + content =3D self.re_escape.sub(r"\\\1", w) + + print(f"- :ref:`{content} <{label}>`\n") + + users =3D v.get("users") + if users and users.strip(" \t\n"): + print(f"Users:\n\t{users.strip("\n").replace('\n', '\n\t')= }\n") + + def check_issues(self): + """Warn about duplicated ABI entries""" + + for what, v in self.what_symbols.items(): + files =3D v.get("file") + if not files: + # Should never happen if the parser works properly + self.log.warning("%s doesn't have a file associated", what) + continue + + if len(files) =3D=3D 1: + continue + + f =3D [] + for fname, lines in sorted(files.items()): + if not lines: + f.append(f"{fname}") + elif len(lines) =3D=3D 1: + f.append(f"{fname}:{lines[0]}") + else: + f.append(f"{fname} lines {", ".join(str(x) for x in li= nes)}") + + self.log.warning("%s is defined %d times: %s", what, len(f), "= ; ".join(f)) + + +class AbiRest: + """Initialize an argparse subparser for rest output""" + + def __init__(self, subparsers): + """Initialize argparse subparsers""" + + parser =3D subparsers.add_parser("rest", + formatter_class=3Dargparse.RawTextH= elpFormatter, + description=3DREST_DESC) + + parser.add_argument("--enable-lineno", action=3D"store_true", + help=3D"enable lineno") + parser.add_argument("--raw", action=3D"store_true", + help=3D"output text as contained in the ABI fi= les. " + "It not used, output will contain dynamic= ally" + " generated cross references when possibl= e.") + parser.add_argument("--no-file", action=3D"store_true", + help=3D"Don't the files section") + parser.add_argument("--show-hints", help=3D"Show-hints") + + parser.set_defaults(func=3Dself.run) + + def run(self, args): + """Run subparser""" + + parser =3D AbiParser(args.dir, debug=3Dargs.debug) + parser.parse_abi() + parser.check_issues() + parser.print_data(args.enable_lineno, args.raw, not args.no_file) + + +class AbiValidate: + """Initialize an argparse subparser for ABI validation""" + + def __init__(self, subparsers): + """Initialize argparse subparsers""" + + parser =3D subparsers.add_parser("validate", + formatter_class=3Dargparse.Argument= DefaultsHelpFormatter, + description=3D"list events") + + parser.set_defaults(func=3Dself.run) + + def run(self, args): + """Run subparser""" + + parser =3D AbiParser(args.dir, debug=3Dargs.debug) + parser.parse_abi() + parser.check_issues() + + +def main(): + """Main program""" + + parser =3D argparse.ArgumentParser(formatter_class=3Dargparse.RawTextH= elpFormatter) + + parser.add_argument("-d", "--debug", type=3Dint, default=3D0, help=3D"= debug level") + parser.add_argument("-D", "--dir", default=3DABI_DIR, help=3DDEBUG_HEL= P) + + subparsers =3D parser.add_subparsers() + + AbiRest(subparsers) + AbiValidate(subparsers) + + args =3D parser.parse_args() + + if args.debug: + level =3D logging.DEBUG + else: + level =3D logging.INFO + + logging.basicConfig(level=3Dlevel, format=3D"[%(levelname)s] %(message= )s") + + if "func" in args: + args.func(args) + else: + sys.exit(f"Please specify a valid command for {sys.argv[0]}") + + +REST_DESC =3D """ +Produce output in ReST format. + +The output is done on two sections: + +- Symbols: show all parsed symbols in alphabetic order; +- Files: cross reference the content of each file with the symbols on it. +""" + +# Call main method +if __name__ =3D=3D "__main__": + main() --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 BE7DB79D0; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; cv=none; b=SuzNxhpJS4Rj89k11juvHL78eQkuN1CUYj48sh/nwNp1QzBcLwEC8JSO6klxOimCZgE1cC0UacH1jKWA4XKaJEMOS4rDCyXCPUDYwQrhYWrZPflbGi8jQSOp3Bt0IV7xY0YXUoPXYyIKNKFrQ3rIFvicyFNTb3lvxrZGS0EvCDA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022796; c=relaxed/simple; bh=UOsqY8X3zaohCbbi+hx08sgCGh+ofd1iPDOFpm4qdJk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=CysB+cDqbDO1hkMFjbKGBYhN8TF95DWGezPU+LTC37UQ4GAEKE65bpMTQW64zpel9CRYSRNiwqaaO79BrMp//gNnSpsI9KPPYuRX6Njj7TJxbHXSbNXiL1uKPscJJpJaOoUfvMq2rJQntcymeQKHfgGrDSwsJl7qmZ99cdsPiqA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=HX+Tpw5x; 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="HX+Tpw5x" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C001BC4CEEF; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=UOsqY8X3zaohCbbi+hx08sgCGh+ofd1iPDOFpm4qdJk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=HX+Tpw5x4nXgeMGfx2tm3Bf4lJWQXoSFm8anHS2ezq7XUGzxlremWmW6XR/c3DoRf UB+oZRiQ5fWdyLFUK0u+ZUf52MoJchBJs9XEpOJTC1/qSNJNKZsM05HAt0uFWcRnX8 bJre4EPbA9vNIBjnXCdJJ1cEiFH8h3COn1YeHLNRT8LoYgTecBe8N+/poa5QuGRErx a0V4JcRDmmiOmGoITso0mh8TH+9B2y+WGVSvSxSxniEnuK5GOYLSdiTSEK+IDfwEUK bEHYo7ip5wKgcTMWwY2lBW/7QUm708w8LT+pfsVPT+rPI8Xr6nnSAmEQBMYaBEzwUq dKBEgZuRZMxHg== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRLH-3yUz; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 14/38] scripts/get_abi.py: add support for symbol search Date: Tue, 28 Jan 2025 01:06:03 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Add support for searching symbols from Documentation/ABI using regular expressions to match the symbols' names. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- scripts/get_abi.py | 76 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/scripts/get_abi.py b/scripts/get_abi.py index 0b5a10e76a3c..93a23cf30ea1 100755 --- a/scripts/get_abi.py +++ b/scripts/get_abi.py @@ -525,6 +525,58 @@ class AbiParser: =20 self.log.warning("%s is defined %d times: %s", what, len(f), "= ; ".join(f)) =20 + def search_symbols(self, expr): + """ Searches for ABI symbols """ + + regex =3D re.compile(expr, re.I) + + found_keys =3D 0 + for t in sorted(self.data.items(), key=3Dlambda x: [0]): + v =3D t[1] + + wtype =3D v.get("type", "") + if wtype =3D=3D "File": + continue + + for what in v.get("what", [""]): + if regex.search(what): + found_keys +=3D 1 + + kernelversion =3D v.get("kernelversion", "").strip(" \= t\n") + date =3D v.get("date", "").strip(" \t\n") + contact =3D v.get("contact", "").strip(" \t\n") + users =3D v.get("users", "").strip(" \t\n") + desc =3D v.get("description", "").strip(" \t\n") + + files =3D [] + for f in v.get("file", ()): + files.append(f[0]) + + what =3D str(found_keys) + ". " + what + title_tag =3D "-" * len(what) + + print(f"\n{what}\n{title_tag}\n") + + if kernelversion: + print(f"Kernel version:\t\t{kernelversion}") + + if date: + print(f"Date:\t\t\t{date}") + + if contact: + print(f"Contact:\t\t{contact}") + + if users: + print(f"Users:\t\t\t{users}") + + print(f"Defined on file{'s'[:len(files) ^ 1]}:\t{", ".= join(files)}") + + if desc: + print(f"\n{desc.strip("\n")}\n") + + if not found_keys: + print(f"Regular expression /{expr}/ not found.") + =20 class AbiRest: """Initialize an argparse subparser for rest output""" @@ -577,6 +629,29 @@ class AbiValidate: parser.check_issues() =20 =20 +class AbiSearch: + """Initialize an argparse subparser for ABI search""" + + def __init__(self, subparsers): + """Initialize argparse subparsers""" + + parser =3D subparsers.add_parser("search", + formatter_class=3Dargparse.Argument= DefaultsHelpFormatter, + description=3D"Search ABI using a r= egular expression") + + parser.add_argument("expression", + help=3D"Case-insensitive search pattern for th= e ABI symbol") + + parser.set_defaults(func=3Dself.run) + + def run(self, args): + """Run subparser""" + + parser =3D AbiParser(args.dir, debug=3Dargs.debug) + parser.parse_abi() + parser.search_symbols(args.expression) + + def main(): """Main program""" =20 @@ -589,6 +664,7 @@ def main(): =20 AbiRest(subparsers) AbiValidate(subparsers) + AbiSearch(subparsers) =20 args =3D parser.parse_args() =20 --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 F402BEAF6; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=du6LSgEVOVeTBnLNW0zrBKmKbUJCMqFMw1UVM3ASJKzpeu51RqoZCCee3xcOMEfr1h1OITWdQvPZmQOjlB6wxe25HtZTLmOPnJOywdxaiuNdfMtO3i/Cj5bTzdzqLNT27PlWHVEjqSGb1b87xG1jKfKD07Ho04IpR5Lx29lFyv8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=Kz1uLR2W8G1KJ3PcmTy6dzY11GbizJ0wg4lGv6G2Aa0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=X9EGA8+5BaPLgSXcc2LuVAsVaIZom+vi9vht9WY8/cUMb6zvN0dQFj8Oq32POcy6Y/7CWA+lc1ACraeoc2yIbasBFA1eO6OgZ5NBMxnPQmF1eWMc0GvQxb0KQp9F8EiHHmKcf5Id3Z7D803wmkfUq+zjyrN6j1Ij8pkZgQXOwJU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Q37w48HH; 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="Q37w48HH" Received: by smtp.kernel.org (Postfix) with ESMTPSA id CB192C4CEF3; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=Kz1uLR2W8G1KJ3PcmTy6dzY11GbizJ0wg4lGv6G2Aa0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Q37w48HH8J8UhYsLOIflAod5F6g8oZbCRRoGS3TMca6/9L+Fc3u9+T/P5xL4DGhRY JJqImBsK4hxEeha3G3MmEIt4To/DdfN4wS6Pu/NXqsBbtzrdpRARp+Eu1Sx2TwBSF2 8jpzAc9IB2MiPG2TKTnb3GDl1YGQy68wUB850/OILqwNNZx1jnSm4vpI33DoYcYHKo 8S4Ncj4b9dPn0kRL6+zlEjG9luu1nROyx4Mvh46mWJiQVT05lpokoJ5Qbzk83dO0LP gg0wmIze/oXY6UPvqAZycy925XR9pNhA1gERnW+7oWQABkx0iBtEaMjDuJN0XzIcRU gMG8GUb9ucNZA== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7h-0000000DRLL-45hO; Tue, 28 Jan 2025 01:06:33 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 15/38] docs: use get_abi.py for ABI generation Date: Tue, 28 Jan 2025 01:06:04 +0100 Message-ID: <54e28a202be41992fa74ffac8c4ee12bb9e9adf5.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Use the new script instead of the old one when generating ABI docs. For now, execute it via exec. Future changes will better integrate it by using the class defined there directly. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/admin-guide/abi-obsolete.rst | 1 - Documentation/admin-guide/abi-removed.rst | 1 - Documentation/admin-guide/abi-stable.rst | 1 - Documentation/admin-guide/abi-testing.rst | 1 - Documentation/sphinx/kernel_abi.py | 10 +++------- 5 files changed, 3 insertions(+), 11 deletions(-) diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/adm= in-guide/abi-obsolete.rst index b655615917f1..6d4d9ab7b8c3 100644 --- a/Documentation/admin-guide/abi-obsolete.rst +++ b/Documentation/admin-guide/abi-obsolete.rst @@ -10,4 +10,3 @@ The description of the interface will document the reason= why it is obsolete and when it can be expected to be removed. =20 .. kernel-abi:: ABI/obsolete - :rst: diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admi= n-guide/abi-removed.rst index ba941c1af178..9fc78af6f077 100644 --- a/Documentation/admin-guide/abi-removed.rst +++ b/Documentation/admin-guide/abi-removed.rst @@ -4,4 +4,3 @@ ABI removed symbols =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 .. kernel-abi:: ABI/removed - :rst: diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin= -guide/abi-stable.rst index 5d738f345333..c47c2a295865 100644 --- a/Documentation/admin-guide/abi-stable.rst +++ b/Documentation/admin-guide/abi-stable.rst @@ -13,4 +13,3 @@ Most interfaces (like syscalls) are expected to never cha= nge and always be available. =20 .. kernel-abi:: ABI/stable - :rst: diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admi= n-guide/abi-testing.rst index a867e6578bf7..40b31985e587 100644 --- a/Documentation/admin-guide/abi-testing.rst +++ b/Documentation/admin-guide/abi-testing.rst @@ -19,4 +19,3 @@ name to the description of these interfaces, so that the = kernel developers can easily notify them if any changes occur. =20 .. kernel-abi:: ABI/testing - :rst: diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kern= el_abi.py index a1887b50a900..fc7500fad119 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -14,7 +14,7 @@ u""" :license: GPL Version 2, June 1991 see Linux/COPYING for details. =20 The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the - scripts/get_abi.pl script to parse the Kernel ABI files. + scripts/get_abi.py script to parse the Kernel ABI files. =20 Overview of directive's argument and options. =20 @@ -66,7 +66,6 @@ class KernelCmd(Directive): =20 option_spec =3D { "debug" : directives.flag, - "rst" : directives.unchanged } =20 def run(self): @@ -77,15 +76,12 @@ class KernelCmd(Directive): srctree =3D os.path.abspath(os.environ["srctree"]) =20 args =3D [ - os.path.join(srctree, 'scripts/get_abi.pl'), + os.path.join(srctree, 'scripts/get_abi.py'), + '-D', os.path.join(srctree, 'Documentation', self.arguments[0]= ), 'rest', '--enable-lineno', - '--dir', os.path.join(srctree, 'Documentation', self.arguments= [0]), ] =20 - if 'rst' in self.options: - args.append('--rst-source') - lines =3D subprocess.check_output(args, cwd=3Dos.path.dirname(doc.= current_source)).decode('utf-8') nodeList =3D self.nestedParse(lines, self.arguments[0]) return nodeList --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 EE3E5DDA8; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=hFWmzNeqEOzsiYurI6TqmqAwGV3DseUlzJc4bQq/y+0HhV8ii+NpIZOUWeLVtefbtevZuM8IA6FxDRiFnKEQ/41ugNYoBwACz6BBBqG9Saiv3Bk1gg2q0zVM20InW4pP46gFei5k9jejwBuToiE41K0hctn8lRVMPhk1ZJTFLzQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=c1DRAW1eND16SBK5p186Mw0Kk3C4nvJXQzIl/jp91wc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=QNqJxd7mXnRTI7yutWIRA841G182lkNbE+MeMMsR5EU97k9oEp8hfOr6uC3jliSGuMLLN1XNrS1lJ2I0ZWY3R4jNitWO4I+8/9XVcxiPNYTbi8hPhgb1ir55zLNKuwShDxQo7x+S43W5/sw/dpDZbxpTlBzJunvQBWxedhekxE4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=FWvyw1QE; 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="FWvyw1QE" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D14E2C4AF0C; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=c1DRAW1eND16SBK5p186Mw0Kk3C4nvJXQzIl/jp91wc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FWvyw1QEUjJvKR133VqP9QTbXl08KOZbqSnoPyuoLkb4F5NBcf6uQBtgjHqr4bPK6 ap7zyqUTMbSrykdP9d8evu34MVMiQAcsg6xuS/FWffOpZ1NKr3mbS/bp7/Qx4yzYvT BwuxcTXqlUQUd69rOsEVy03eZSuD/Eo7+8+SztD8l6fYtwTlyTE8p2mvTbaS+btgTA Qhfz7u210Jv3L00g7Hg5po6aoWGQVGqf+AMa+82K922VaWa1xShj5B1s6OtQZUrvvo SqsZJkdkPpA0fGeZohDWQMUmRd4pMFFvY9A9DBORz2NxGtzDgev7xlq75SsLPRrdS6 M8OKds+XeFAxg== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRLP-00cQ; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 16/38] scripts/get_abi.py: optimize parse_abi() function Date: Tue, 28 Jan 2025 01:06:05 +0100 Message-ID: <238cbe14607880e99d7e6cbaa3f046dfaf96dcd2.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Instead of using glob, use a recursive function to parse all files. Such change reduces the total excecution time by 15% with my SSD disks. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- scripts/get_abi.py | 57 ++++++++++++++++++++++++++++++---------------- 1 file changed, 38 insertions(+), 19 deletions(-) diff --git a/scripts/get_abi.py b/scripts/get_abi.py index 93a23cf30ea1..73613fb29c1c 100755 --- a/scripts/get_abi.py +++ b/scripts/get_abi.py @@ -13,7 +13,6 @@ import os import re import sys =20 -from glob import glob from pprint import pformat from random import randrange, seed =20 @@ -59,7 +58,11 @@ class AbiParser: self.file_refs =3D {} self.what_refs =3D {} =20 + # Ignore files that contain such suffixes + self.ignore_suffixes =3D (".rej", ".org", ".orig", ".bak", "~") + # Regular expressions used on parser + self.re_abi_dir =3D re.compile(r"(.*)" + ABI_DIR) self.re_tag =3D re.compile(r"(\S+)(:\s*)(.*)", re.I) self.re_valid =3D re.compile(self.TAGS) self.re_start_spc =3D re.compile(r"(\s*)(\S.*)") @@ -335,26 +338,42 @@ class AbiParser: for w in fdata.what: self.add_symbol(what=3Dw, fname=3Dfname, xref=3Dfdata.= key) =20 - def parse_abi(self): + def _parse_abi(self, root=3DNone): + """Internal function to parse documentation ABI recursively""" + + if not root: + root =3D self.directory + + with os.scandir(root) as obj: + for entry in obj: + name =3D os.path.join(root, entry.name) + + if entry.is_dir(): + self.parse_abi(name) + continue + + if not entry.is_file(): + continue + + basename =3D os.path.basename(name) + + if basename =3D=3D "README": + continue + + if basename.startswith("."): + continue + + if basename.endswith(self.ignore_suffixes): + continue + + path =3D self.re_abi_dir.sub("", os.path.dirname(name)) + + self.parse_file(name, path, basename) + + def parse_abi(self, root=3DNone): """Parse documentation ABI""" =20 - ignore_suffixes =3D ("rej", "org", "orig", "bak", "~") - re_abi =3D re.compile(r".*" + ABI_DIR) - - for fname in glob(os.path.join(self.directory, "**"), recursive=3D= True): - if os.path.isdir(fname): - continue - - basename =3D os.path.basename(fname) - - if basename =3D=3D "README": - continue - if basename.startswith(".") or basename.endswith(ignore_suffix= es): - continue - - path =3D re_abi.sub("", os.path.dirname(fname)) - - self.parse_file(fname, path, basename) + self._parse_abi(root) =20 if self.debug & DEBUG_DUMP_ABI_STRUCTS: self.log.debug(pformat(self.data)) --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 DBE09C2ED; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=QvguzV/cS6XC0ZEeFhAFVvML4/rSepB5U/lMBcS6/DsnNhDPNhS/ZXNSLG9TsRDX8wk6nG7BQAybJKFVtqPNSL5iFL41B3rkoy5XEY49B2qaRJ3aewuKRDr0D/kh68SqGR0G4b3oNcRhyX5A7P5ErVngo92fUbqtpwAlbctTWDM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=TU7X7H9KcDN4F2n1V6tnT6V+uLjYBbHR0Lyzk9YmCgU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=q/bQ5IWxeNE6g51Y+8g6v2usvsJFgYMMU+cJWv1JfnVtQzgrFqFh5z5Q9MyAgD8CAXuDZ72cUznY3w2ygy/A419HVsgwzzZOxO/2ih7rjSIGi9RI0Tlf7TWCcL/gP7jKX4IVhfWYokdEScZ6xbINjgHqn4EZe4k1E8WeQRwWvgc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=XZtLvJFC; 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="XZtLvJFC" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D7548C4CEF4; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=TU7X7H9KcDN4F2n1V6tnT6V+uLjYBbHR0Lyzk9YmCgU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XZtLvJFCPElgsXdvhNFgzqPOa23krxpnxtz6hDDyxJKscZB9ZYhiH7TPzPNTSa5RU 4a9PaZSl89lRyYcGkvA1/Bs54Lef0ufD5Owwt7Gjw9/KIcnM4AyvDOQKPiUGXAObMV IRqtC1+W5pDt/ra8ujLllS1i4ACUmAbHZLvTjbAKVPcyEyQ5YDS5tbchRlwEMSs8KT c/ltYM3zJsnEtw9w5eBBfX+Acu4nISb8L1Upc3SVFme8d9ct4vFkZM+R/O5/3O+N7A EW4uaQsFiEIXrua6i2I3e13JUYiCrO7cVofcr31Lhhb6xJddZLu1PWqirsvcY4N+l1 YbCG06HIa4GlA== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRLT-07kE; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 17/38] scripts/get_abi.py: use an interactor for ReST output Date: Tue, 28 Jan 2025 01:06:06 +0100 Message-ID: <72a53ca85e554b0c1fb90488d55aa62ec1d7defe.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Instead of printing all results line per line, use an interactor to return each variable as a separate message. This won't change much when using it via command line, but it will help Sphinx integration by providing an interactor that could be used there to handle ABI symbol by symbol. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- scripts/get_abi.py | 52 ++++++++++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/scripts/get_abi.py b/scripts/get_abi.py index 73613fb29c1c..2aec1f9dc5aa 100755 --- a/scripts/get_abi.py +++ b/scripts/get_abi.py @@ -349,7 +349,7 @@ class AbiParser: name =3D os.path.join(root, entry.name) =20 if entry.is_dir(): - self.parse_abi(name) + self._parse_abi(name) continue =20 if not entry.is_file(): @@ -378,14 +378,14 @@ class AbiParser: if self.debug & DEBUG_DUMP_ABI_STRUCTS: self.log.debug(pformat(self.data)) =20 - def print_desc_txt(self, desc): + def desc_txt(self, desc): """Print description as found inside ABI files""" =20 desc =3D desc.strip(" \t\n") =20 - print(desc + "\n") + return desc + "\n\n" =20 - def print_desc_rst(self, desc): + def desc_rst(self, desc): """Enrich ReST output by creating cross-references""" =20 # Remove title markups from the description @@ -439,9 +439,9 @@ class AbiParser: =20 new_desc +=3D d + "\n" =20 - print(new_desc + "\n") + return new_desc + "\n\n" =20 - def print_data(self, enable_lineno, output_in_txt, show_file=3DFalse): + def doc(self, enable_lineno, output_in_txt, show_file=3DFalse): """Print ABI at stdout""" =20 part =3D None @@ -456,9 +456,11 @@ class AbiParser: if not show_file and wtype =3D=3D "File": continue =20 + msg =3D "" + if enable_lineno: ln =3D v.get("line_no", 1) - print(f".. LINENO {file_ref[0][0]}#{ln}\n") + msg +=3D f".. LINENO {file_ref[0][0]}#{ln}\n\n" =20 if wtype !=3D "File": cur_part =3D names[0] @@ -470,9 +472,9 @@ class AbiParser: =20 if cur_part and cur_part !=3D part: part =3D cur_part - print(f"{part}\n{"-" * len(part)}\n") + msg +=3D f"{part}\n{"-" * len(part)}\n\n" =20 - print(f".. _{key}:\n") + msg +=3D f".. _{key}:\n\n" =20 max_len =3D 0 for i in range(0, len(names)): # pylint: disable= =3DC0200 @@ -480,45 +482,47 @@ class AbiParser: =20 max_len =3D max(max_len, len(names[i])) =20 - print("+-" + "-" * max_len + "-+") + msg +=3D "+-" + "-" * max_len + "-+\n" for name in names: - print(f"| {name}" + " " * (max_len - len(name)) + " |") - print("+-" + "-" * max_len + "-+") - print() + msg +=3D f"| {name}" + " " * (max_len - len(name)) + "= |\n" + msg +=3D "+-" + "-" * max_len + "-+\n" + msg +=3D "\n" =20 for ref in file_ref: if wtype =3D=3D "File": - print(f".. _{ref[1]}:\n") + msg +=3D f".. _{ref[1]}:\n\n" else: base =3D os.path.basename(ref[0]) - print(f"Defined on file :ref:`{base} <{ref[1]}>`\n") + msg +=3D f"Defined on file :ref:`{base} <{ref[1]}>`\n\= n" =20 if wtype =3D=3D "File": - print(f"{names[0]}\n{"-" * len(names[0])}\n") + msg +=3D f"{names[0]}\n{"-" * len(names[0])}\n\n" =20 desc =3D v.get("description") if not desc and wtype !=3D "File": - print(f"DESCRIPTION MISSING for {names[0]}\n") + msg +=3D f"DESCRIPTION MISSING for {names[0]}\n\n" =20 if desc: if output_in_txt: - self.print_desc_txt(desc) + msg +=3D self.desc_txt(desc) else: - self.print_desc_rst(desc) + msg +=3D self.desc_rst(desc) =20 symbols =3D v.get("symbols") if symbols: - print("Has the following ABI:\n") + msg +=3D "Has the following ABI:\n\n" =20 for w, label in symbols: # Escape special chars from content content =3D self.re_escape.sub(r"\\\1", w) =20 - print(f"- :ref:`{content} <{label}>`\n") + msg +=3D f"- :ref:`{content} <{label}>`\n\n" =20 users =3D v.get("users") if users and users.strip(" \t\n"): - print(f"Users:\n\t{users.strip("\n").replace('\n', '\n\t')= }\n") + msg +=3D f"Users:\n\t{users.strip("\n").replace('\n', '\n\= t')}\n\n" + + yield msg =20 def check_issues(self): """Warn about duplicated ABI entries""" @@ -625,7 +629,9 @@ class AbiRest: parser =3D AbiParser(args.dir, debug=3Dargs.debug) parser.parse_abi() parser.check_issues() - parser.print_data(args.enable_lineno, args.raw, not args.no_file) + + for msg in parser.doc(args.enable_lineno, args.raw, not args.no_fi= le): + print(msg) =20 =20 class AbiValidate: --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 F3EF4EAD7; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=eh2Hyi2qN4in66Co5qprtYWTmTY0GFlObM4htVSgmoFf6TVNFOpLNp1Dwe31ZNh6yZZd0+dDMhfYPGG2klWEUkCV1DAUir+vF8gwa/vS/tLbjN/WOOM7RkKUZGR54Y1XFEnYRcr5tfEcjWlPtGMRG+AbFulxvJ9XkQIcfz4Wj7I= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=/+kwnUbLgQbBGzPsJj4pevKvmAZb3+SqJUlcwCOPCc4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=aauV69pXH9yG7FsNL8HPogkrqEEdJUkssidPU3nyFsEHLsrwc3cSCcEgiQDgNIZySs07U2hQyivziOR7lDYdkphfePa+0UkbGRj+Teju5g5/uGNyJf31EdWtybg/saZ0hP9+zTRHKEuYSohh/HA2cv8F2NDjvfVTFBCI+5BGn7E= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=kBWIL7l3; 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="kBWIL7l3" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D33CAC4AF0F; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=/+kwnUbLgQbBGzPsJj4pevKvmAZb3+SqJUlcwCOPCc4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=kBWIL7l34bzSzECMQI8jSVIeZCPGyH4KShAClPTYT0qAuQhk+O6j4BoM9yn/KpbO4 +ylfsWD/WhczQGo1unne4PHTgO0ExMUSoidouhQi2U9NRA8XYpjMqGgL0AhtkGlwjD GTnEE5I5rj2SasVu6f2f6iZyl58HDfm2Jarins/zXYthD161+LqWCjc0wpJnPVz9q/ ory4YhAc6F6WDuJhEG+23mituJoYp3TjC3F1Ow4hVH9TvkyMOPzmjAzcErEZ3vDWrc 2e1ng3L7B07Cu9f1PCOKpEI8l+s187x8WDnSvgloCLGxJf0TPNLiarew/uysjW2zsi tBAimKndFh+Ew== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRLX-0Eh7; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 18/38] docs: sphinx/kernel_abi: use AbiParser directly Date: Tue, 28 Jan 2025 01:06:07 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Instead of running get_abi.py script, import AbiParser class and handle messages directly there using an interactor. This shold save some memory, as there's no need to exec python inside the Sphinx python extension. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/sphinx/kernel_abi.py | 26 +++++++++++++++----------- scripts/get_abi.py | 2 +- 2 files changed, 16 insertions(+), 12 deletions(-) diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kern= el_abi.py index fc7500fad119..93d537d8cb6c 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -42,6 +42,11 @@ from docutils.parsers.rst import directives, Directive from sphinx.util.docutils import switch_source_input from sphinx.util import logging =20 +srctree =3D os.path.abspath(os.environ["srctree"]) +sys.path.insert(0, os.path.join(srctree, "scripts")) + +from get_abi import AbiParser + __version__ =3D "1.0" =20 =20 @@ -65,7 +70,7 @@ class KernelCmd(Directive): logger =3D logging.getLogger('kernel_abi') =20 option_spec =3D { - "debug" : directives.flag, + "debug": directives.flag, } =20 def run(self): @@ -73,18 +78,17 @@ class KernelCmd(Directive): if not doc.settings.file_insertion_enabled: raise self.warning("docutils: file insertion disabled") =20 - srctree =3D os.path.abspath(os.environ["srctree"]) + path =3D os.path.join(srctree, "Documentation", self.arguments[0]) + parser =3D AbiParser(path, logger=3Dself.logger) + parser.parse_abi() + parser.check_issues() =20 - args =3D [ - os.path.join(srctree, 'scripts/get_abi.py'), - '-D', os.path.join(srctree, 'Documentation', self.arguments[0]= ), - 'rest', - '--enable-lineno', - ] + msg =3D "" + for m in parser.doc(enable_lineno=3DTrue, show_file=3DTrue): + msg +=3D m =20 - lines =3D subprocess.check_output(args, cwd=3Dos.path.dirname(doc.= current_source)).decode('utf-8') - nodeList =3D self.nestedParse(lines, self.arguments[0]) - return nodeList + node =3D self.nested_parse(msg, self.arguments[0]) + return node =20 def nested_parse(self, lines, fname): env =3D self.state.document.settings.env diff --git a/scripts/get_abi.py b/scripts/get_abi.py index 2aec1f9dc5aa..3a8dcff85dc2 100755 --- a/scripts/get_abi.py +++ b/scripts/get_abi.py @@ -441,7 +441,7 @@ class AbiParser: =20 return new_desc + "\n\n" =20 - def doc(self, enable_lineno, output_in_txt, show_file=3DFalse): + def doc(self, enable_lineno=3DFalse, output_in_txt=3DFalse, show_file= =3DFalse): """Print ABI at stdout""" =20 part =3D None --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 0D39F101F2; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=F15FFFJxhTMK9TW2SHYIFjDeO8L+SZaXtpOGvJcRI05WTYXH2Secoy8bGAzTFgk1/xXl2cbMkGdEHF5e9SRBCPLZ/nQSt33dvE91JtueScwXGKjkvdc+c7KUOCaZ0RbmDgGO+vfEvWY8jMM767eu6lH86YxHIbDNQ2Txs1FIaV8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=Ig/wrssKDOB8y1m2J/EooG9A8FvmBFRH9/TycqOd21E=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=MsYiH5QrMVOON3qiGKO/E1CQ8FVdROzATsQridnnrcG3GVTEOCD2oW2vvDRbEpC7XEwg2jgohxiPVDX1AY070unuPr6t5zQYIJXmQhNjtDNIXnKDSd2NhgZZUW1HeQWu2maoAewyjQDnMJWaEMQv2ZNJiPeLBvcRqt5dsovQJcM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=SVC2MNhR; 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="SVC2MNhR" Received: by smtp.kernel.org (Postfix) with ESMTPSA id DBBE3C4CEF7; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=Ig/wrssKDOB8y1m2J/EooG9A8FvmBFRH9/TycqOd21E=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=SVC2MNhRvYZRnrULbrk14qiuRYZr+EbHxmhLiw/LKs5FIfJTPakgjzvELglMjFUin hEu/iWJ5DmdFpzLvbdQTQAnwCTYpmcV/Uyc+G1WUfiseqO1ml9tYDw6LKbwTlr482b gFxiNeVJnoVozjE5ii3jjfYi7qwC+GBDrwkUy1yfM5o4Upp72yeN6ZmIpQ2iYlmDIO ggGTZoTsNGtMkNHQCfhhWzYfRKdpqMTtazjGDbHFiHuXUqWz6BOy6NBUX6+iz12YAu 5fEGVObZ+qLX7fW/JZ1Nt3SUdcm85cDK9OOtAEAdOpQ8vLntyBsFqZD1QWdRjrXT/l bQN1wXQV9caAw== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRLb-0LCE; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 19/38] docs: sphinx/kernel_abi: reduce buffer usage for ABI messages Date: Tue, 28 Jan 2025 01:06:08 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Instead of producing a big message with all ABI contents and then parse as a whole, simplify the code by handling each ABI symbol in separate. As an additional benefit, there's no need to place file/line nubers inlined at the data and use a regex to convert them. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/sphinx/kernel_abi.py | 76 +++++++++++++++--------------- scripts/get_abi.py | 17 +++---- 2 files changed, 48 insertions(+), 45 deletions(-) diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kern= el_abi.py index 93d537d8cb6c..025a4f02e1a4 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -68,6 +68,7 @@ class KernelCmd(Directive): has_content =3D False final_argument_whitespace =3D True logger =3D logging.getLogger('kernel_abi') + parser =3D None =20 option_spec =3D { "debug": directives.flag, @@ -79,59 +80,60 @@ class KernelCmd(Directive): raise self.warning("docutils: file insertion disabled") =20 path =3D os.path.join(srctree, "Documentation", self.arguments[0]) - parser =3D AbiParser(path, logger=3Dself.logger) - parser.parse_abi() - parser.check_issues() + self.parser =3D AbiParser(path, logger=3Dself.logger) + self.parser.parse_abi() + self.parser.check_issues() =20 - msg =3D "" - for m in parser.doc(enable_lineno=3DTrue, show_file=3DTrue): - msg +=3D m - - node =3D self.nested_parse(msg, self.arguments[0]) + node =3D self.nested_parse(None, self.arguments[0]) return node =20 - def nested_parse(self, lines, fname): + def nested_parse(self, data, fname): env =3D self.state.document.settings.env content =3D ViewList() node =3D nodes.section() =20 - if "debug" in self.options: - code_block =3D "\n\n.. code-block:: rst\n :linenos:\n" - for line in lines.split("\n"): - code_block +=3D "\n " + line - lines =3D code_block + "\n\n" + if data is not None: + # Handles the .rst file + for line in data.split("\n"): + content.append(line, fname, 0) =20 - line_regex =3D re.compile(r"^\.\. LINENO (\S+)\#([0-9]+)$") - ln =3D 0 - n =3D 0 - f =3D fname + self.do_parse(content, node) =20 - for line in lines.split("\n"): - n =3D n + 1 - match =3D line_regex.search(line) - if match: - new_f =3D match.group(1) + else: + # Handles the ABI parser content, symbol by symbol =20 - # Sphinx parser is lazy: it stops parsing contents in the - # middle, if it is too big. So, handle it per input file - if new_f !=3D f and content: - self.do_parse(content, node) - content =3D ViewList() + old_f =3D fname + n =3D 0 + for msg, f, ln in self.parser.doc(): + msg_list =3D msg.split("\n") + if "debug" in self.options: + lines =3D [ + "", "", ".. code-block:: rst", + " :linenos:", "" + ] + for m in msg_list: + lines.append(" " + m) + else: + lines =3D msg_list =20 + for line in lines: + # sphinx counts lines from 0 + content.append(line, f, ln - 1) + n +=3D 1 + + if f !=3D old_f: # Add the file to Sphinx build dependencies env.note_dependency(os.path.abspath(f)) =20 - f =3D new_f + old_f =3D f =20 - # sphinx counts lines from 0 - ln =3D int(match.group(2)) - 1 - else: - content.append(line, f, ln) + # Sphinx doesn't like to parse big messages. So, let's + # add content symbol by symbol + if content: + self.do_parse(content, node) + content =3D ViewList() =20 - self.logger.info("%s: parsed %i lines" % (fname, n)) - - if content: - self.do_parse(content, node) + self.logger.info("%s: parsed %i lines" % (fname, n)) =20 return node.children =20 diff --git a/scripts/get_abi.py b/scripts/get_abi.py index 3a8dcff85dc2..b57f46b91828 100755 --- a/scripts/get_abi.py +++ b/scripts/get_abi.py @@ -441,7 +441,7 @@ class AbiParser: =20 return new_desc + "\n\n" =20 - def doc(self, enable_lineno=3DFalse, output_in_txt=3DFalse, show_file= =3DFalse): + def doc(self, output_in_txt=3DFalse, show_file=3DTrue): """Print ABI at stdout""" =20 part =3D None @@ -458,10 +458,6 @@ class AbiParser: =20 msg =3D "" =20 - if enable_lineno: - ln =3D v.get("line_no", 1) - msg +=3D f".. LINENO {file_ref[0][0]}#{ln}\n\n" - if wtype !=3D "File": cur_part =3D names[0] if cur_part.find("/") >=3D 0: @@ -522,7 +518,9 @@ class AbiParser: if users and users.strip(" \t\n"): msg +=3D f"Users:\n\t{users.strip("\n").replace('\n', '\n\= t')}\n\n" =20 - yield msg + ln =3D v.get("line_no", 1) + + yield (msg, file_ref[0][0], ln) =20 def check_issues(self): """Warn about duplicated ABI entries""" @@ -630,8 +628,11 @@ class AbiRest: parser.parse_abi() parser.check_issues() =20 - for msg in parser.doc(args.enable_lineno, args.raw, not args.no_fi= le): - print(msg) + for t in parser.doc(args.raw, not args.no_file): + if args.enable_lineno: + print (f".. LINENO {t[1]}#{t[2]}\n\n") + + print(t[0]) =20 =20 class AbiValidate: --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 F08FCDDC3; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=E2uAVUSp2xmY3Mq8RLcgepHGSRIwYBSiuUSoVcel7X4D1x0WOtJ569O1jHBe2MaBvlltt5eBx5j/KBkrPS8/PAlKV9ZD5wwJ6jvNyqjvzVlWFoK215y+QacH4+DR0FDXWJ5A0xInqv4C7cXf+ZTdXxSkuXrEusyzXgBceRNLx+U= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=vHZ5PLWJNhBy8t8pbmqXOz9J8zS085ioE7uaQ7Z50XE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=UdINI4uxc1F4oiki4WX8+/jqmtIZ/tKgVErecmQNkcNwXWJbiI70mLCI1OLi30ivDfVXx2TgdyHfRoIYgw1ElH+jW/NaxNIqpVULsbuzjb1TQqULB+3xO0S+30WKhkiPBjH2DdtJ7qvP408cdfwZUroc44PNPD6GzcYYT8ZlTKA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=LG8cTvV0; 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="LG8cTvV0" Received: by smtp.kernel.org (Postfix) with ESMTPSA id DE245C4CEF5; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022795; bh=vHZ5PLWJNhBy8t8pbmqXOz9J8zS085ioE7uaQ7Z50XE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=LG8cTvV0oeGa9O3EXe+1aOV5F6FJ10NGWwauy9MJ3qrv9+cDImt+KE9fMJBjC81SB PbIzDovkpMudreF1+RUusHdLkWQs8WIzi3tJ+AxrFv7mWalCG4uEIQjVOrVmVnTOtK PUL1U8stVCZnsh5ZOZmsy9BSL1X9Ov8oRbcqCMJnvtxVci/SrX4KHZI82JOW8m2cAs 6PljwS9Z3kYOPuwELubYyndysPStUutgOsnsNrCY28qKPCdVyv3gJhyi6QPBL9AC8a nrNnG4Lz+3xv4+3hdrqys3RAHOTzkSOGbgCXwYs2NB9h/oL1yPE5thQXAgS4ZtvqK9 hQu9CAwR3U5jg== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRLf-0Rt9; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 20/38] docs: sphinx/kernel_abi: properly split lines Date: Tue, 28 Jan 2025 01:06:09 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Sphinx doesn't like to have lines split with str.split("\n"). Instead, it uses its own splitter, with handles line breaks the way Spinx expects. Not using it cause issues at the output files. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/sphinx/kernel_abi.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kern= el_abi.py index 025a4f02e1a4..2408ba7a3981 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -36,7 +36,7 @@ import os import re import sys =20 -from docutils import nodes +from docutils import nodes, statemachine from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive from sphinx.util.docutils import switch_source_input @@ -105,7 +105,8 @@ class KernelCmd(Directive): old_f =3D fname n =3D 0 for msg, f, ln in self.parser.doc(): - msg_list =3D msg.split("\n") + msg_list =3D statemachine.string2lines(msg, tab_width, + convert_whitespace=3D= True) if "debug" in self.options: lines =3D [ "", "", ".. code-block:: rst", --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 1A2DE125DF; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=ksFWmxQ6zJgfuEqxRJ/gXTcjwent5XSiYTByQ4lL+BMRnz5gM7GIOQyggfXkZQyW+scfC5ZFATD8JIdaAYEr84WLLCdYWIANBj3MV/Iy81nFwUTdc6iOZkykbtBYANYlPa5JFTW7DxmFxCIl7eQq6CjxCZFQIX+6hA2nYoGBAKY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=SzTGx5/sOV13eTwJaBN4/jb4Imr5I3tKH5BWnaIinIk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=u80fkXOtbJ5xSn65e/X8fmt7GaXoZKJ5LLwjq116+LjCH8cS6CK36WK7781XXRIyp1sZ89Jepdc0XFSJPw6e7mTG9K0uuwg3wyg7re4hs7zGSIBuY0rIwbCxwM0C+TxmKyK9hfye47hPI+VLo0eK487gWb5DRKI5xtoK5PxKZpk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=QBflgNJo; 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="QBflgNJo" Received: by smtp.kernel.org (Postfix) with ESMTPSA id F3519C4AF11; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=SzTGx5/sOV13eTwJaBN4/jb4Imr5I3tKH5BWnaIinIk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=QBflgNJoWUrhuHUv2Ijw4448VfYp2VM1sI8IsVxffsPHxHhLonqtrMNydrukfxdqb OxxI3DGcUAPDgs99/ldM3UcuGmCTTZocK/gqwwNiqFaUfJBb/ttdnel8WNOahazm/V ND5O6IuXoYOEx75LMYOnRc99kArYfwdKPQO4jPobgm8bZz2R669K01QBQQF9rXfT14 Svxy5Npdo2alcmIaw7rFACaFxk5yQf23suNab877J/0a8z/bDVlgNqke2eWmD53UVh 6C2YPK5p37k6gI4rysPAemCt3A6l9qk8viVFTEQ7w7cFgclIcyWgdyB4gEKohTRagB A73Mp+2LYhZSw== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRLj-0Ybc; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 21/38] scripts/get_abi.pl: Add filtering capabilities to rest output Date: Tue, 28 Jan 2025 01:06:10 +0100 Message-ID: <30be453db4fbad9cb2d21c3ad9fde5c7a1fb838b.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" This way, Sphinx ABI extension can parse symbols only once, while keep displaying results in separate files. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- scripts/get_abi.py | 34 ++++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/scripts/get_abi.py b/scripts/get_abi.py index b57f46b91828..6d7fa8fbca34 100755 --- a/scripts/get_abi.py +++ b/scripts/get_abi.py @@ -173,6 +173,7 @@ class AbiParser: self.data[fdata.key] =3D { "what": [content], "file": [fdata.file_ref], + "path": fdata.ftype, "line_no": fdata.ln, } =20 @@ -195,8 +196,6 @@ class AbiParser: if new_what: fdata.label =3D "" =20 - self.data[fdata.key]["type"] =3D fdata.ftype - if "description" in self.data[fdata.key]: self.data[fdata.key]["description"] +=3D "\n\n" =20 @@ -312,6 +311,7 @@ class AbiParser: fdata.nametag =3D {} fdata.nametag["what"] =3D [f"File {path}/{basename}"] fdata.nametag["type"] =3D "File" + fdata.nametag["path"] =3D fdata.ftype fdata.nametag["file"] =3D [fdata.file_ref] fdata.nametag["line_no"] =3D 1 fdata.nametag["description"] =3D "" @@ -441,7 +441,8 @@ class AbiParser: =20 return new_desc + "\n\n" =20 - def doc(self, output_in_txt=3DFalse, show_file=3DTrue): + def doc(self, output_in_txt=3DFalse, show_symbols=3DTrue, show_file=3D= True, + filter_path=3DNone): """Print ABI at stdout""" =20 part =3D None @@ -449,12 +450,20 @@ class AbiParser: key=3Dlambda x: (x[1].get("type", ""), x[1].get("what"))): =20 - wtype =3D v.get("type", "Var") + wtype =3D v.get("type", "Symbol") file_ref =3D v.get("file") names =3D v.get("what", [""]) =20 - if not show_file and wtype =3D=3D "File": - continue + if wtype =3D=3D "File": + if not show_file: + continue + else: + if not show_symbols: + continue + + if filter_path: + if v.get("path") !=3D filter_path: + continue =20 msg =3D "" =20 @@ -616,7 +625,11 @@ class AbiRest: "It not used, output will contain dynamic= ally" " generated cross references when possibl= e.") parser.add_argument("--no-file", action=3D"store_true", - help=3D"Don't the files section") + help=3D"Don't show files section") + parser.add_argument("--no-symbols", action=3D"store_true", + help=3D"Don't show symbols section") + parser.add_argument("--filter", + help=3D"Filter a section of ABI (e..g stable, = testing, obsolete, removed)") parser.add_argument("--show-hints", help=3D"Show-hints") =20 parser.set_defaults(func=3Dself.run) @@ -628,7 +641,12 @@ class AbiRest: parser.parse_abi() parser.check_issues() =20 - for t in parser.doc(args.raw, not args.no_file): + for t in parser.doc(args.raw, show_file=3Dnot args.no_file, + show_symbols=3Dnot args.no_symbols, + filter_path=3Dargs.filter): + + # As line number is returned at the tuple, artifically place + # them as a comment tag if one wants to debug troubles there if args.enable_lineno: print (f".. LINENO {t[1]}#{t[2]}\n\n") =20 --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 094CCF513; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=XW6RCg3wmcgXye6jGLQF0fE9Wyons71o5yC0BBGjpVZjDzecq6HFfRcmBLDZYUmq1E4SvrWcQpwGAny7IiFtph2bCGG1SdvqJlF1srnoJpZbsEGBIaBdcKr+3Fe8cZXeaWxciLa8TrmZmazzoNLnJaCDkPTuv12oIPzUVQdfshg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=b2P1ol5GI5wxTTgp3WD4NLr24nQ4aqzFQ0yVTuulMl0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=YJMfJvxV/e9iI+oWivMmrF+eGeNfNHXVmE/ha88Bet4YrOmR/FPsv6gXBeYoXJXsmr/DqxAzK0Ptjm12LBcjTwn4VlfpNgXebtuza3gCZZqRDgE8+dC7cxLOZwr86jo0pYWgDS3bP/Ynty6nsJ9KPtwwTkVcHSKWJalp2L5QJUk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=LE60cN3J; 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="LE60cN3J" Received: by smtp.kernel.org (Postfix) with ESMTPSA id E9E9DC4CEF6; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=b2P1ol5GI5wxTTgp3WD4NLr24nQ4aqzFQ0yVTuulMl0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=LE60cN3J5NvMoAiEJs3LEuIZokRRIMHuzyO9j0r6duWl6f7FH8zUZj2TnkopnvoWl va/h0jW3QtBwEbEPKX7Z2S2QmklSmI8tOqi3QbxBlBV6bIClA2i2P8oLKR5UZxhJYz ThwcVnUreOKL1tdqSSeQgAw4evWlShfWAvAUEa22pBijZxePWVCGnxqV2fwmHVLQA2 TJvC7sxyPIduFK5x0G/t/c5808QtG8NdzTJbr2e99oJh/QyL27Qb6wiWipYBif2/+3 qsXVPdQ3jAccnlbeu2P2hZ42pqqj5yQVR1rbjVKF9mKEtS8Z6pgqRRZdvugGV7YLAN RSartAhirlCCA== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRLn-0fFN; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 22/38] scripts/get_abi.pl: add support to parse ABI README file Date: Tue, 28 Jan 2025 01:06:11 +0100 Message-ID: <3c900177b187a8073cffb644de12dfe84c51c1dd.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" The Documentation/ABI/README file is currently outside the documentation tree. Yet, it may still provide some useful information. Add it to the documentation parsing. As a plus, this avoids a warning when detecting missing cross-references. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- scripts/get_abi.py | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/scripts/get_abi.py b/scripts/get_abi.py index 6d7fa8fbca34..3cde278b8e4c 100755 --- a/scripts/get_abi.py +++ b/scripts/get_abi.py @@ -276,6 +276,16 @@ class AbiParser: if content: self.warn(fdata, "Unexpected content", line) =20 + def parse_readme(self, nametag, fname): + """Parse ABI README file""" + + with open(fname, "r", encoding=3D"utf8", errors=3D"backslashreplac= e") as fp: + nametag["description"] =3D "```\n" + for line in fp: + nametag["description"] +=3D " " + line + + nametag["description"] +=3D "```\n" + def parse_file(self, fname, path, basename): """Parse a single file""" =20 @@ -322,6 +332,10 @@ class AbiParser: if self.debug & DEBUG_WHAT_OPEN: self.log.debug("Opening file %s", fname) =20 + if basename =3D=3D "README": + self.parse_readme(fdata.nametag, fname) + return + with open(fname, "r", encoding=3D"utf8", errors=3D"backslashreplac= e") as fp: for line in fp: fdata.ln +=3D 1 @@ -357,9 +371,6 @@ class AbiParser: =20 basename =3D os.path.basename(name) =20 - if basename =3D=3D "README": - continue - if basename.startswith("."): continue =20 @@ -462,8 +473,12 @@ class AbiParser: continue =20 if filter_path: - if v.get("path") !=3D filter_path: - continue + if filter_path =3D=3D "README": + if not names[0].endswith("README"): + continue + else: + if v.get("path") !=3D filter_path: + continue =20 msg =3D "" =20 --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 4C53D273F9; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=YstaKXCEQCOFaN3sUeIqTrsuOGleDyyGJz/pUG+PMkWnkCLR7bQmNEwZHMXAKUyhlgm5HgcgBlYUkhDDot8q6z84MUmjJzBIIs3vLrDEE6qd6O5A4Ury0CWp7dARtuoPqZ49eCicAYvqK1N6ioQWj2l8TZ4s+ZUktWqnY4zpJes= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=1eS0ENZhyS5NgGwt57b7o8bqQ+da8byhs9yHPVKsnog=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=kIZJ5s/L0VVTZgaSS8tkloxGn9+0DD9rkfCmd6pJKNkIAGDC9dm5HiB3HJnoQcJxTWeDESi8s6yupmvIBbwWLe9k5RmQgzxXfA9NSSAewERyzYL8OtTLkNFACKJP584xM+Wl7gDcf2egdkt+/XhifpXn1X91F6VS5SFRBykoqt0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=plexcGaF; 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="plexcGaF" Received: by smtp.kernel.org (Postfix) with ESMTPSA id F2E21C4CEFD; Tue, 28 Jan 2025 00:06:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=1eS0ENZhyS5NgGwt57b7o8bqQ+da8byhs9yHPVKsnog=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=plexcGaFVSwfy7BhB/x//HcKHsPg94lIY0HZOOKZoYCMt99hwQVqQ3H703OKcL9QM k9eyIEjIgpkwGg4boxn4rQYCMrbqoOYxx3Y48TncY5DnQ/YNbgY7OLsevjg0int4WZ RhJjuameSzxtJlfokKKe4HG7+sPjJT88bWk/mHMj4Vsf4BGfWldgDUuUTft+krqOVV XZ3pgkUsufiH8sQVVy0stWeSx66rsAVVzCLlhwmByk007W712NWtk8tRxVO694E+lt mJaRFIHlJ4piukHEmnvgc8haQlADs3lBKlgcdUxkJGsMTRXmdtGQYHaGD5CmzW/ctQ jTdRw7qQCs9UQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRLr-0m6X; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 23/38] docs: sphinx/kernel_abi: parse ABI files only once Date: Tue, 28 Jan 2025 01:06:12 +0100 Message-ID: <52b1fc2f56d6a2eee0d8da2ec08e133de8207402.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Right now, the logic parses ABI files on 4 steps, one for each directory. While this is fine in principle, by doing that, not all symbol cross-references will be created. Change the logic to do the parsing only once in order to get a global dictionary to be used when creating ABI cross-references. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/admin-guide/abi-obsolete.rst | 2 +- Documentation/admin-guide/abi-removed.rst | 2 +- Documentation/admin-guide/abi-stable.rst | 2 +- Documentation/admin-guide/abi-testing.rst | 2 +- Documentation/sphinx/kernel_abi.py | 115 ++++++++++++--------- scripts/get_abi.py | 22 ++-- 6 files changed, 81 insertions(+), 64 deletions(-) diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/adm= in-guide/abi-obsolete.rst index 6d4d9ab7b8c3..bdef91d2cea4 100644 --- a/Documentation/admin-guide/abi-obsolete.rst +++ b/Documentation/admin-guide/abi-obsolete.rst @@ -9,4 +9,4 @@ marked to be removed at some later point in time. The description of the interface will document the reason why it is obsolete and when it can be expected to be removed. =20 -.. kernel-abi:: ABI/obsolete +.. kernel-abi:: obsolete diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admi= n-guide/abi-removed.rst index 9fc78af6f077..bea0608b8442 100644 --- a/Documentation/admin-guide/abi-removed.rst +++ b/Documentation/admin-guide/abi-removed.rst @@ -3,4 +3,4 @@ ABI removed symbols =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -.. kernel-abi:: ABI/removed +.. kernel-abi:: removed diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin= -guide/abi-stable.rst index c47c2a295865..33637c0d4fd5 100644 --- a/Documentation/admin-guide/abi-stable.rst +++ b/Documentation/admin-guide/abi-stable.rst @@ -12,4 +12,4 @@ for at least 2 years. Most interfaces (like syscalls) are expected to never change and always be available. =20 -.. kernel-abi:: ABI/stable +.. kernel-abi:: stable diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admi= n-guide/abi-testing.rst index 40b31985e587..55054985a8ff 100644 --- a/Documentation/admin-guide/abi-testing.rst +++ b/Documentation/admin-guide/abi-testing.rst @@ -18,4 +18,4 @@ Programs that use these interfaces are strongly encourage= d to add their name to the description of these interfaces, so that the kernel developers can easily notify them if any changes occur. =20 -.. kernel-abi:: ABI/testing +.. kernel-abi:: testing diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kern= el_abi.py index 2408ba7a3981..6d1b34e44d46 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -49,6 +49,13 @@ from get_abi import AbiParser =20 __version__ =3D "1.0" =20 +logger =3D logging.getLogger('kernel_abi') +path =3D os.path.join(srctree, "Documentation/ABI") + +# Parse ABI symbols only once +kernel_abi =3D AbiParser(path, logger=3Dlogger) +kernel_abi.parse_abi() +kernel_abi.check_issues() =20 def setup(app): =20 @@ -64,14 +71,15 @@ class KernelCmd(Directive): u"""KernelABI (``kernel-abi``) directive""" =20 required_arguments =3D 1 - optional_arguments =3D 2 + optional_arguments =3D 3 has_content =3D False final_argument_whitespace =3D True - logger =3D logging.getLogger('kernel_abi') parser =3D None =20 option_spec =3D { "debug": directives.flag, + "no-symbols": directives.flag, + "no-files": directives.flag, } =20 def run(self): @@ -79,62 +87,67 @@ class KernelCmd(Directive): if not doc.settings.file_insertion_enabled: raise self.warning("docutils: file insertion disabled") =20 - path =3D os.path.join(srctree, "Documentation", self.arguments[0]) - self.parser =3D AbiParser(path, logger=3Dself.logger) - self.parser.parse_abi() - self.parser.check_issues() - - node =3D self.nested_parse(None, self.arguments[0]) - return node - - def nested_parse(self, data, fname): env =3D self.state.document.settings.env content =3D ViewList() node =3D nodes.section() =20 - if data is not None: - # Handles the .rst file - for line in data.split("\n"): - content.append(line, fname, 0) + abi_type =3D self.arguments[0] =20 - self.do_parse(content, node) + if "no-symbols" in self.options: + show_symbols =3D False + else: + show_symbols =3D True =20 + if "no-files" in self.options: + show_file =3D False + else: + show_file =3D True + + tab_width =3D self.options.get('tab-width', + self.state.document.settings.tab_widt= h) + + old_f =3D None + n =3D 0 + n_sym =3D 0 + for msg, f, ln in kernel_abi.doc(show_file=3Dshow_file, + show_symbols=3Dshow_symbols, + filter_path=3Dabi_type): + n_sym +=3D 1 + msg_list =3D statemachine.string2lines(msg, tab_width, + convert_whitespace=3DTrue) + if "debug" in self.options: + lines =3D [ + "", "", ".. code-block:: rst", + " :linenos:", "" + ] + for m in msg_list: + lines.append(" " + m) + else: + lines =3D msg_list + + for line in lines: + # sphinx counts lines from 0 + content.append(line, f, ln - 1) + n +=3D 1 + + if f !=3D old_f: + # Add the file to Sphinx build dependencies + env.note_dependency(os.path.abspath(f)) + + old_f =3D f + + # Sphinx doesn't like to parse big messages. So, let's + # add content symbol by symbol + if content: + self.do_parse(content, node) + content =3D ViewList() + + if show_symbols and not show_file: + logger.verbose("%s ABI: %i symbols (%i ReST lines)" % (abi_typ= e, n_sym, n)) + elif not show_symbols and show_file: + logger.verbose("%s ABI: %i files (%i ReST lines)" % (abi_type,= n_sym, n)) else: - # Handles the ABI parser content, symbol by symbol - - old_f =3D fname - n =3D 0 - for msg, f, ln in self.parser.doc(): - msg_list =3D statemachine.string2lines(msg, tab_width, - convert_whitespace=3D= True) - if "debug" in self.options: - lines =3D [ - "", "", ".. code-block:: rst", - " :linenos:", "" - ] - for m in msg_list: - lines.append(" " + m) - else: - lines =3D msg_list - - for line in lines: - # sphinx counts lines from 0 - content.append(line, f, ln - 1) - n +=3D 1 - - if f !=3D old_f: - # Add the file to Sphinx build dependencies - env.note_dependency(os.path.abspath(f)) - - old_f =3D f - - # Sphinx doesn't like to parse big messages. So, let's - # add content symbol by symbol - if content: - self.do_parse(content, node) - content =3D ViewList() - - self.logger.info("%s: parsed %i lines" % (fname, n)) + logger.verbose("%s ABI: %i data (%i ReST lines)" % (abi_type, = n_sym, n)) =20 return node.children =20 diff --git a/scripts/get_abi.py b/scripts/get_abi.py index 3cde278b8e4c..7435ed1071b8 100755 --- a/scripts/get_abi.py +++ b/scripts/get_abi.py @@ -279,12 +279,20 @@ class AbiParser: def parse_readme(self, nametag, fname): """Parse ABI README file""" =20 + nametag["what"] =3D ["ABI file contents"] + nametag["path"] =3D "README" with open(fname, "r", encoding=3D"utf8", errors=3D"backslashreplac= e") as fp: - nametag["description"] =3D "```\n" for line in fp: - nametag["description"] +=3D " " + line + match =3D self.re_tag.match(line) + if match: + new =3D match.group(1).lower() =20 - nametag["description"] +=3D "```\n" + match =3D self.re_valid.search(new) + if match: + nametag["description"] +=3D "\n:" + line + continue + + nametag["description"] +=3D line =20 def parse_file(self, fname, path, basename): """Parse a single file""" @@ -473,12 +481,8 @@ class AbiParser: continue =20 if filter_path: - if filter_path =3D=3D "README": - if not names[0].endswith("README"): - continue - else: - if v.get("path") !=3D filter_path: - continue + if v.get("path") !=3D filter_path: + continue =20 msg =3D "" =20 --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 3F2301F95C; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=XmNrtIoB3QZDzsXgfxXXqLVqQGqDsG9l29yCxYyvWAygAr2SFW0CBu9VPK/IHVzxqAztPraxJt5wqsSQkLSpiWEM/wxL8c/ppaxrbyySsYDUNG0hiDzBEzRfZKFLwctPH1er2yGolZC9FKGbd6HmsfRPQD0QNburLZcl5h2ES6c= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=5Ehk+UnXsY+f4nC8KlN3P04pRtl7e+QgRfiunel5DWg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=jpQAGAemB/pHXKYrholfBd+6nGmqb1mRoeadAWKcL1zcG6QAXZ0wYsb2xE4xdF5JRNkRAcndC+OPFn/V3fFwKlx7/KyvfkKRRjVVhrCnNUYpdPOG0Om1Z38O+M43LQDzoPxXGia0Rbrn0/o/qJdxzqPfrA8J29sjxnR6X+jzPBw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=upgUv5WF; 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="upgUv5WF" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1C58CC116C6; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=5Ehk+UnXsY+f4nC8KlN3P04pRtl7e+QgRfiunel5DWg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=upgUv5WFiK5kZdSUAY+aTYNfiyi34unoqVc5MdsArfguMyK90exrrQW+zNT2g9qoQ H4sjAKtXOXDJ6XhqV5gqIoWvjSUpIw9vwmHq3ld07PjLn32EZn7nZt8+muZx2mXYQp 7pcTPLK7N27Gd8vp0Rx3KrDc4mHbu/5cdtf4gMVKu1Ef1zUjUjOIlPwMUFOgzl07TF 0E68M2m7HRSJljr/IDkakzJ1st/ZWNP9dsQcA/8lHm+sUkAZQgqUsAH8NQMl/71Qse d2zsZDIdTNMJ6pSROpgIrbqgU0EeYLikkdP9cP2Zs2jTha1HaGxW50FZyybthG2gou m23NgsI1CCHRQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRLv-0swn; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 24/38] docs: admin-guide/abi: split files from symbols Date: Tue, 28 Jan 2025 01:06:13 +0100 Message-ID: <0fb924b00797d0966d824224762b11595d44cacb.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Now that get_abi has gained support for filtering its output, split ABI symbols from files at the html output. That makes pages smaller and easier to navigate. As an additional bonus, as it will paralelize files handling, it gives an additional performance improvement. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/admin-guide/abi-obsolete-files.rst | 7 +++++++ Documentation/admin-guide/abi-obsolete.rst | 1 + Documentation/admin-guide/abi-readme-file.rst | 6 ++++++ Documentation/admin-guide/abi-removed-files.rst | 7 +++++++ Documentation/admin-guide/abi-removed.rst | 1 + Documentation/admin-guide/abi-stable-files.rst | 7 +++++++ Documentation/admin-guide/abi-stable.rst | 1 + Documentation/admin-guide/abi-testing-files.rst | 7 +++++++ Documentation/admin-guide/abi-testing.rst | 1 + Documentation/admin-guide/abi.rst | 15 +++++++++++++++ 10 files changed, 53 insertions(+) create mode 100644 Documentation/admin-guide/abi-obsolete-files.rst create mode 100644 Documentation/admin-guide/abi-readme-file.rst create mode 100644 Documentation/admin-guide/abi-removed-files.rst create mode 100644 Documentation/admin-guide/abi-stable-files.rst create mode 100644 Documentation/admin-guide/abi-testing-files.rst diff --git a/Documentation/admin-guide/abi-obsolete-files.rst b/Documentati= on/admin-guide/abi-obsolete-files.rst new file mode 100644 index 000000000000..3061a916b4b5 --- /dev/null +++ b/Documentation/admin-guide/abi-obsolete-files.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Obsolete ABI Files +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. kernel-abi:: obsolete + :no-symbols: diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/adm= in-guide/abi-obsolete.rst index bdef91d2cea4..640f3903e847 100644 --- a/Documentation/admin-guide/abi-obsolete.rst +++ b/Documentation/admin-guide/abi-obsolete.rst @@ -10,3 +10,4 @@ The description of the interface will document the reason= why it is obsolete and when it can be expected to be removed. =20 .. kernel-abi:: obsolete + :no-files: diff --git a/Documentation/admin-guide/abi-readme-file.rst b/Documentation/= admin-guide/abi-readme-file.rst new file mode 100644 index 000000000000..6172e4ccbda2 --- /dev/null +++ b/Documentation/admin-guide/abi-readme-file.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +ABI README +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. kernel-abi:: README diff --git a/Documentation/admin-guide/abi-removed-files.rst b/Documentatio= n/admin-guide/abi-removed-files.rst new file mode 100644 index 000000000000..f1bdfadd2ec4 --- /dev/null +++ b/Documentation/admin-guide/abi-removed-files.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Removed ABI Files +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. kernel-abi:: removed + :no-symbols: diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admi= n-guide/abi-removed.rst index bea0608b8442..88832d3eacd6 100644 --- a/Documentation/admin-guide/abi-removed.rst +++ b/Documentation/admin-guide/abi-removed.rst @@ -4,3 +4,4 @@ ABI removed symbols =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 .. kernel-abi:: removed + :no-files: diff --git a/Documentation/admin-guide/abi-stable-files.rst b/Documentation= /admin-guide/abi-stable-files.rst new file mode 100644 index 000000000000..f867738fc178 --- /dev/null +++ b/Documentation/admin-guide/abi-stable-files.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Stable ABI Files +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. kernel-abi:: stable + :no-symbols: diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin= -guide/abi-stable.rst index 33637c0d4fd5..528c68401f4b 100644 --- a/Documentation/admin-guide/abi-stable.rst +++ b/Documentation/admin-guide/abi-stable.rst @@ -13,3 +13,4 @@ Most interfaces (like syscalls) are expected to never cha= nge and always be available. =20 .. kernel-abi:: stable + :no-files: diff --git a/Documentation/admin-guide/abi-testing-files.rst b/Documentatio= n/admin-guide/abi-testing-files.rst new file mode 100644 index 000000000000..1da868e42fdb --- /dev/null +++ b/Documentation/admin-guide/abi-testing-files.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Testing ABI Files +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. kernel-abi:: testing + :no-symbols: diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admi= n-guide/abi-testing.rst index 55054985a8ff..6153ebd38e2d 100644 --- a/Documentation/admin-guide/abi-testing.rst +++ b/Documentation/admin-guide/abi-testing.rst @@ -19,3 +19,4 @@ name to the description of these interfaces, so that the = kernel developers can easily notify them if any changes occur. =20 .. kernel-abi:: testing + :no-files: diff --git a/Documentation/admin-guide/abi.rst b/Documentation/admin-guide/= abi.rst index 64e772bde943..15a2dcb1388c 100644 --- a/Documentation/admin-guide/abi.rst +++ b/Documentation/admin-guide/abi.rst @@ -4,6 +4,9 @@ Linux ABI description =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 +ABI symbols +----------- + .. toctree:: :maxdepth: 2 =20 @@ -11,3 +14,15 @@ Linux ABI description abi-testing abi-obsolete abi-removed + +ABI files +--------- + +.. toctree:: + :maxdepth: 2 + + abi-readme-file + abi-stable-files + abi-testing-files + abi-obsolete-files + abi-removed-files --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 353A81E531; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=hTlYKrE+sAN+zm+ZCi++ifIT7sdXDTa2JuUnpKbq/o3OFbpBi1TFrcoKl34Q80ToJfp9KYYLsoiznqR7ZwtEE+rc3ktyn7XmYitM99t6JMWxqC2zB0qiu6/q+EkaUcFrv6vr7Qwta/1u8SOEZMyR0YcQsXckEAvdpKr2PpblF2c= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=lDLPH7kUn/3QJcu8UsvVEA9i6yHiVOXJJkOvW7zCEkY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=heSZvPdZRVtVjojvgTQtMWFj/bi/2GEX3AdyJ2vVdlf//arSxmmiP8q12PkfakOMrIyHkuC2c7rZR0iIK7A2dvW9gz3lCWzHTLwbD87nka8TkKCdUqliESRdeQJpGiVUXYM1P0QebUQUFE7ulcxUUl3H0NJe/q76RcIGTgd4LXQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=sZY9ADmT; 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="sZY9ADmT" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1BE40C116B1; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=lDLPH7kUn/3QJcu8UsvVEA9i6yHiVOXJJkOvW7zCEkY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sZY9ADmTIv/spHSMKkyM5ei5mSJQPp/xJtOD9WIt+iWQgOfyGJj3j9twECJZ+71/8 Y1DgeKvmgeRF8TDPZNA3FEZC6W4StqFxQFWszBLZnDwISWhOqD5f+g/Bj7duvJckbF DCvye64iC0PiK6fxNg7BdIhy8ioAXwqjUDeNomjtRdw5Zy15huWmdLLoWTrZq1Chi9 Wc5AvctqrEGMv/BRs7M6xdP6JLQDrzj2iNkY5AU0dInhhp6GfV6yAs6kyeQI0eWF5/ tBn4oCIur5kR81tJ/XgIxF8SeE/6+otZKUY1TKIuN1K1Hb3CL6ykyKSx5QKRMIHzAV YDnmEpljVnJaQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRLz-0zdR; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 25/38] docs: sphinx/automarkup: add cross-references for ABI Date: Tue, 28 Jan 2025 01:06:14 +0100 Message-ID: <27d09dbf5e3020b4f4fb17db9f8b7c76690b24be.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Now that all ABI files are handled together, we can add a feature at automarkup for it to generate cross-references for ABI symbols. The cross-reference logic can produce references for all existing files, except for README (as this is not parsed). For symbols, they need to be an exact match of what it is described at the docs, which is not always true due to wildcards. If symbols at /sys /proc and /config are identical, a cross-reference will be used. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/sphinx/automarkup.py | 45 ++++++++++++++++++++++++++++++ scripts/get_abi.py | 11 ++++++++ 2 files changed, 56 insertions(+) diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/auto= markup.py index a413f8dd5115..7d91c39b4ca6 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -11,6 +11,8 @@ from sphinx.errors import NoUri import re from itertools import chain =20 +from kernel_abi import kernel_abi + # # Python 2 lacks re.ASCII... # @@ -48,6 +50,8 @@ RE_typedef =3D re.compile(r'\b(typedef)\s+([a-zA-Z_]\w+)'= , flags=3Dascii_p3) # an optional extension # RE_doc =3D re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.(rst|txt)') +RE_abi_file =3D re.compile(r'(\bDocumentation/ABI/[\w\-/]+)') +RE_abi_symbol =3D re.compile(r'(\b/(sys|config|proc)/[\w\-/]+)') =20 RE_namespace =3D re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$') =20 @@ -84,10 +88,14 @@ def markup_refs(docname, app, node): # Associate each regex with the function that will markup its matches # markup_func_sphinx2 =3D {RE_doc: markup_doc_ref, + RE_abi_file: markup_abi_ref, + RE_abi_symbol: markup_abi_ref, RE_function: markup_c_ref, RE_generic_type: markup_c_ref} =20 markup_func_sphinx3 =3D {RE_doc: markup_doc_ref, + RE_abi_file: markup_abi_ref, + RE_abi_symbol: markup_abi_ref, RE_function: markup_func_ref_sphinx3, RE_struct: markup_c_ref, RE_union: markup_c_ref, @@ -270,6 +278,43 @@ def markup_doc_ref(docname, app, match): else: return nodes.Text(match.group(0)) =20 +# +# Try to replace a documentation reference of the form Documentation/ABI/.= .. +# with a cross reference to that page +# +def markup_abi_ref(docname, app, match): + stddom =3D app.env.domains['std'] + # + # Go through the dance of getting an xref out of the std domain + # + fname =3D match.group(1) + target =3D kernel_abi.xref(fname) + + # Kernel ABI doesn't describe such file or symbol + if not target: + return nodes.Text(match.group(0)) + + pxref =3D addnodes.pending_xref('', refdomain =3D 'std', reftype =3D '= ref', + reftarget =3D target, modname =3D None, + classname =3D None, refexplicit =3D Fals= e) + + # + # XXX The Latex builder will throw NoUri exceptions here, + # work around that by ignoring them. + # + try: + xref =3D stddom.resolve_xref(app.env, docname, app.builder, 'ref', + target, pxref, None) + except NoUri: + xref =3D None + # + # Return the xref if we got it; otherwise just return the plain text. + # + if xref: + return xref + else: + return nodes.Text(match.group(0)) + def get_c_namespace(app, docname): source =3D app.env.doc2path(docname) with open(source) as f: diff --git a/scripts/get_abi.py b/scripts/get_abi.py index 7435ed1071b8..faae51201504 100755 --- a/scripts/get_abi.py +++ b/scripts/get_abi.py @@ -404,6 +404,17 @@ class AbiParser: =20 return desc + "\n\n" =20 + def xref(self, fname): + """ + Converts a Documentation/ABI + basename into a ReST cross-reference + """ + + xref =3D self.file_refs.get(fname) + if not xref: + return None + else: + return xref + def desc_rst(self, desc): """Enrich ReST output by creating cross-references""" =20 --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 2A33C18052; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=NJtVvaBzuU4nflso9rBlVI63Gv+8fLReH3isoYMGzlukx9CyDZeUvof5NxDExPfBTU23iJnkTlXyzelsG89P7xbsmU2EdN5OWHfpuWBCKyFk19Tq+e2JBjT+npOllZRbNnKeiNmX4MS7JNeM2X33sennPKm+xQcFcUDo256oFw0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=svI6Yddco5aZW7xRQWuqtZoHkCHFW0NEnfZcjQdfwEk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=KVhMcibc+iKG0PU3pzXYxGiYwrzoZt4m0GBOIkpTqa9gmTlWFAHM6FPzXbGwtcERBtM/aAD2oN9xMS/5u6D4i6mMvGvaTfzMRdFWldXCV/ZJwUqagrr5dfLmAOjEsq0clwoUAR6lVyDV2ubs+S7xMt8020ThnNZIAl4FjQQv9kI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=M6Rz+mlA; 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="M6Rz+mlA" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 0AF90C113CF; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=svI6Yddco5aZW7xRQWuqtZoHkCHFW0NEnfZcjQdfwEk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=M6Rz+mlAUamSJNBj3NZwDFbo2SLKdKGrJgD3PlS7oX5ze/ueCmACplFNoLKBxhFfN FzI8sXNkwL4PE2SMbzUPgDYVqvf/IjOh4/uLmqxkpE+4jKbg3+YKUd6SBzE0ekFJXy AOHmW/KdbAsJyqM0oIpAlOUvM7ouAQvuxtrLq8esqndxRUbZgvECuIOn1q6GoQ1TD3 Iiq6YfdSrkL1zfJVxkRaXHF27hJ2GaV21mdK8d+pmvaPfGXYVBCyGbVcr/4VhXHaAn 4CIv2bYCAWTGRqRf/NyGpj3aUlTE2jOYwpPLYraTKy3sTWwsH+M4FBvGXfdZzqwPV5 GSO3TM2muIZng== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRM3-16Ve; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 26/38] docs: sphinx/kernel_abi: avoid warnings during Sphinx module init Date: Tue, 28 Jan 2025 01:06:15 +0100 Message-ID: <87b384db252838a858243f4aaa3fdf58360a96dd.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Sphinx logging system doesn't like warnings during module load, as it understands that such logs are produced at the wrong time: WARNING: while setting up extension automarkup: /sys/devices/system/cpu/cp= uX/topology/physical_package_id is defined 2 times: /new_devel/v4l/docs/Doc= umentation/ABI/stable/sysfs-devices-system-cpu:27; /new_devel/v4l/docs/Docu= mentation/ABI/testing/sysfs-devices-system-cpu:70 WARNING: while setting up extension automarkup: /sys/devices/system/cpu/cp= uX/topology/ppin is defined 2 times: /new_devel/v4l/docs/Documentation/ABI/= stable/sysfs-devices-system-cpu:89; /new_devel/v4l/docs/Documentation/ABI/t= esting/sysfs-devices-system-cpu:70 So, use a function to allocate/process ABI files and use it to be called at kernel_abi.py, as automarkup also needs it to produce the right cross-references. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/sphinx/automarkup.py | 4 +++- Documentation/sphinx/kernel_abi.py | 23 +++++++++++++++++++---- 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/auto= markup.py index 7d91c39b4ca6..22defc18d6d2 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -11,7 +11,7 @@ from sphinx.errors import NoUri import re from itertools import chain =20 -from kernel_abi import kernel_abi +from kernel_abi import get_kernel_abi =20 # # Python 2 lacks re.ASCII... @@ -287,6 +287,8 @@ def markup_abi_ref(docname, app, match): # # Go through the dance of getting an xref out of the std domain # + kernel_abi =3D get_kernel_abi() + fname =3D match.group(1) target =3D kernel_abi.xref(fname) =20 diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kern= el_abi.py index 6d1b34e44d46..379a877b75f9 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -52,10 +52,23 @@ __version__ =3D "1.0" logger =3D logging.getLogger('kernel_abi') path =3D os.path.join(srctree, "Documentation/ABI") =20 -# Parse ABI symbols only once -kernel_abi =3D AbiParser(path, logger=3Dlogger) -kernel_abi.parse_abi() -kernel_abi.check_issues() +_kernel_abi =3D None + +def get_kernel_abi(): + u""" + Initialize kernel_abi global var, if not initialized yet. + + This is needed to avoid warnings during Sphinx module initialization. + """ + global _kernel_abi + + if not _kernel_abi: + # Parse ABI symbols only once + _kernel_abi =3D AbiParser(path, logger=3Dlogger) + _kernel_abi.parse_abi() + _kernel_abi.check_issues() + + return _kernel_abi =20 def setup(app): =20 @@ -83,6 +96,8 @@ class KernelCmd(Directive): } =20 def run(self): + kernel_abi =3D get_kernel_abi() + doc =3D self.state.document if not doc.settings.file_insertion_enabled: raise self.warning("docutils: file insertion disabled") --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 55FD82942A; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=pY0EWBp7B1iMPkmLarvRaBkUs52b5EyE6mJGZ4jNQM8VHUFnq3nQwEsmHL3atW2AkRenbiBszSVwemXzBciR+fbfkGuxO1N+vf3o2vaC1wZnLvn7FKbhKXxjxeKH3nV3GQzmCqpP32jALPAUimplYFuiFE/yaynriA7T0L1+9ws= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=vE+9+3UxmiGLqZ+P2f3eoFwC3xI72QmwbpGYU9Ci2HU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=a4NPeMMYBf7FcZTd3ymyqCbPedcMpXJ1hSWSCGOMGQjMglW17iso8Sjg1uOXZ8WvmtYfbIaOJvIUQ+5KJeiLs4flVGM+rVph6R19fbsZxrUTxQBP/uRP2t9iou3vBCVActlOaO6xnpxpyZfITDx1WbrEktQN//KnHxJo2WFl3Ow= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=fKV1aLLa; 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="fKV1aLLa" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2A9AAC4AF15; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=vE+9+3UxmiGLqZ+P2f3eoFwC3xI72QmwbpGYU9Ci2HU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=fKV1aLLakdCDqs2C3AO7AtssbF3hr6M/W6Rnux5ziktu24JGgbX8j1MqdH7x3cg1U yGrXGfW0BVr/VTXQqhL8iyTP7zUX1jgUPZBFYSZA+jq7pVVKSF43+SYFimkw8wAwXR KYTRmNDbtlpn5Mp8W1pkG5+9lw9bsmgvghWK5JWjSKAyUaF9rt08kYdEWBX2piJgT0 sb2qSJndvq3c20LmH2ON4gvPSaY6IYpfN4DHWA+HY1GZxgaSx/POR1t77h80N31PF1 AlB5FCB4UQrXMFBdGQkEn68KW5/pYHyuxuae/Q8CNZ6nthFWSVxGksviJsCJ8qOZdL P5ME4IiTW/AxQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRM7-1DRX; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 27/38] scripts/get_abi.py: Rename title name for ABI files Date: Tue, 28 Jan 2025 01:06:16 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" This makes them look better when generating cross-references. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- scripts/get_abi.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/get_abi.py b/scripts/get_abi.py index faae51201504..1c9c6b23a6fb 100755 --- a/scripts/get_abi.py +++ b/scripts/get_abi.py @@ -327,7 +327,7 @@ class AbiParser: fdata.ftype =3D path.split("/")[0] =20 fdata.nametag =3D {} - fdata.nametag["what"] =3D [f"File {path}/{basename}"] + fdata.nametag["what"] =3D [f"ABI file {path}/{basename}"] fdata.nametag["type"] =3D "File" fdata.nametag["path"] =3D fdata.ftype fdata.nametag["file"] =3D [fdata.file_ref] --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 4F7252745E; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=r74HxhSC+kaRan1F59t1e8eVhLc1ePPg56LR5+kTLqOAc3sbX1ci0sb3vsHXVjaSgsxS7ss/TsTj3JF3vkIt+zFjd6dCW1IziD254CW6LIk0xDh0f2RHLSfQtA3b2hUkfd37D4ngbl7SMGbxkD3Lf+Av1UMPijEZLj1RPyYvAJk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=t4nvCsVaeq/JWg5HRJsbxqzjIAI8bXe8VWVi54lXQhI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Y7XnOIBEfUx7pKp8haxDzZcYs818qYUL+onThIvJ6zcZuskvvQjmROGm9BxjHZrONE3uzGGEkd+ImoLojCtC3qdYO06xPjapqyfocI43KY3VWbczf1I5l/wxxhlaho+RFOFfxaqoKXbxwxywMqApfB+WXeIkYmANF69SpRgMfl8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=uizMTlw3; 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="uizMTlw3" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2259CC116D0; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=t4nvCsVaeq/JWg5HRJsbxqzjIAI8bXe8VWVi54lXQhI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uizMTlw3vIR+hYPDDHbpcKJXb+uPJb04sZkTThJ2qVb7GR87ceZ3Fq7wXw2eUk+qF il94sZbuVVZqcCGjYN28HuRPGm3191iCsj53fJxBdn+M2TvCPndbb5LzHElzUYKSF6 NKa5YyxvBf9X6aOTPdnE8k1GiOpMwA9IwLlI2gS5dQ+ALydS6bnvV8AKXQSGeAymS2 +9mtWlGIU4oYsPjwzeLGsPdXzBMyEIpmbI4ocNGksjyVOTv24afaIerLyF0vHf+JkV Pu+QBwNkdZWtoUKSRQi2pONMn4u/fgbeyT0V5QahIYqnVFd2jOc/k0nkhYetWXNJuh ivFW6P3Ffypjg== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRMB-1KOc; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , Sean Young , linux-kernel@vger.kernel.org, linux-media@vger.kernel.org Subject: [RFC v2 28/38] docs: media: Allow creating cross-references for RC ABI Date: Tue, 28 Jan 2025 01:06:17 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Now that Documentation/ABI is processed by automarkup, let it generate cross-references for RC sysfs devnodes. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/sphinx/automarkup.py | 17 +++++++++++++---- .../userspace-api/media/rc/rc-sysfs-nodes.rst | 2 +- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/auto= markup.py index 22defc18d6d2..03bb7020f5cb 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -88,13 +88,13 @@ def markup_refs(docname, app, node): # Associate each regex with the function that will markup its matches # markup_func_sphinx2 =3D {RE_doc: markup_doc_ref, - RE_abi_file: markup_abi_ref, + RE_abi_file: markup_abi_file_ref, RE_abi_symbol: markup_abi_ref, RE_function: markup_c_ref, RE_generic_type: markup_c_ref} =20 markup_func_sphinx3 =3D {RE_doc: markup_doc_ref, - RE_abi_file: markup_abi_ref, + RE_abi_file: markup_abi_file_ref, RE_abi_symbol: markup_abi_ref, RE_function: markup_func_ref_sphinx3, RE_struct: markup_c_ref, @@ -279,10 +279,10 @@ def markup_doc_ref(docname, app, match): return nodes.Text(match.group(0)) =20 # -# Try to replace a documentation reference of the form Documentation/ABI/.= .. +# Try to replace a documentation reference for ABI symbols and files # with a cross reference to that page # -def markup_abi_ref(docname, app, match): +def markup_abi_ref(docname, app, match, warning=3DFalse): stddom =3D app.env.domains['std'] # # Go through the dance of getting an xref out of the std domain @@ -294,6 +294,8 @@ def markup_abi_ref(docname, app, match): =20 # Kernel ABI doesn't describe such file or symbol if not target: + if warning: + kernel_abi.log.warning("%s not found", fname) return nodes.Text(match.group(0)) =20 pxref =3D addnodes.pending_xref('', refdomain =3D 'std', reftype =3D '= ref', @@ -317,6 +319,13 @@ def markup_abi_ref(docname, app, match): else: return nodes.Text(match.group(0)) =20 +# +# Variant of markup_abi_ref() that warns whan a reference is not found +# +def markup_abi_file_ref(docname, app, match): + return markup_abi_ref(docname, app, match, warning=3DTrue) + + def get_c_namespace(app, docname): source =3D app.env.doc2path(docname) with open(source) as f: diff --git a/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst b/Docu= mentation/userspace-api/media/rc/rc-sysfs-nodes.rst index 34d6a0a1f4d3..70b5966aaff8 100644 --- a/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst +++ b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst @@ -6,7 +6,7 @@ Remote Controller's sysfs nodes ******************************* =20 -As defined at ``Documentation/ABI/testing/sysfs-class-rc``, those are +As defined at Documentation/ABI/testing/sysfs-class-rc, those are the sysfs nodes that control the Remote Controllers: =20 =20 --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 5C1DE29D0C; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=hCdvw3nh0zghwTNzJuTFLz0p5PiwA+g8bGuqP0AZPpcGg+2WHQ8LCzhUt93Z/RJevXAUQsxYVRVjLGayssm37XPj4fqpEmsoctE8/F/ekmXDGGYsIachlDq1/vDfL76p7x2M817G0IR5f2CxflDD/YuimveLBdykwzczyH9CciY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=jccSIU0oVQ+cUZk0PyT/X/eDo6j67p5MwmFseC4sEcw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=GeM0Gkskm0rb1+kgpV/gA4V6w6ECbulj0VJmPkS3wtA5JT95G4BSIwvIIhdbp6/EwdWEJoV5uekbXNKzYTGYb6cDBL5U3a80qrobpK+MDO26WG/UqKQjEdzUEqMMZPZVUfu+1hWjDqSNOU5NSsmsdDf9NWOpZ6Gz6nmsVVvhG6g= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=TLABo9yZ; 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="TLABo9yZ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 288B8C4AF16; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=jccSIU0oVQ+cUZk0PyT/X/eDo6j67p5MwmFseC4sEcw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=TLABo9yZoHOvKnzZUQtxxrEr9SnP73U360OfsxNJzlI1dhsPdLTKQw9kt0Eh0zNhh pge3EMH6uewJ+YWX6Q2HCeEncWOciPf5Or32/K2fPaJZeEr6nJZOYJBu3qSzlILHIn BeLgEGkYYow7mFxBCIYNwe6rDn9v4pTGX48BFOwnmh6v3nVJxLqXql3ZJzFd4dM+UO zNhK0X1/7QPqt0MAhvsZzvH1ilpOof6KUmj2PivUGHSy7CZCEx4V0DIpgaYeeNkLjH HMR3qSX7nHRb0sFa+JHH7sofBrr7QJffXJnaZmCVtpgEdSbuq7I3wiH/yJatYET6hU 8IsU13RupORHQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRMF-1Rvo; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , Andreas Noever , Michael Jamet , Mika Westerberg , Yehezkel Bernat , linux-kernel@vger.kernel.org, linux-usb@vger.kernel.org Subject: [RFC v2 29/38] docs: thunderbolt: Allow creating cross-references for ABI Date: Tue, 28 Jan 2025 01:06:18 +0100 Message-ID: <3895db4d11575b2d3e98b066a35498aeadf749dd.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Now that Documentation/ABI is processed by automarkup, let it generate cross-references for the corresponding ABI file. Signed-off-by: Mauro Carvalho Chehab Acked-by: Mika Westerberg Reported-by: Akira Yokosawa --- Documentation/admin-guide/thunderbolt.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admi= n-guide/thunderbolt.rst index 2ed79f41a411..d0502691dfa1 100644 --- a/Documentation/admin-guide/thunderbolt.rst +++ b/Documentation/admin-guide/thunderbolt.rst @@ -28,7 +28,7 @@ should be a userspace tool that handles all the low-level= details, keeps a database of the authorized devices and prompts users for new connections. =20 More details about the sysfs interface for Thunderbolt devices can be -found in ``Documentation/ABI/testing/sysfs-bus-thunderbolt``. +found in Documentation/ABI/testing/sysfs-bus-thunderbolt. =20 Those users who just want to connect any device without any sort of manual work can add following line to --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 5E53F2A1BA; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=naUcvmnrTq+RrHzVV7vJ7iV/tzUCp6qGpv1tslsBjiZeRr3DZtmuqEcoIGCAF+gOnPMkinWP7xty2kucIeXKtsqV9Xdu4zYgCMX0BLSJ68hIwAvKUufZpf76qk8Ahw5EOAtQINPKmeS9D3qm+c8DuI04dfcikJtfew06QJTUxkE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=EIzss4+nVhmBM716ght5tv9bi2u8EXv+0cXIqsZnexs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=MlGrucWUphuXAzHFicMDqczmAokQk4CmFSnjf0H+/e2HJlrCBmJPNMns5JnGIlqwHG5g/XYWy+0w505mc64Ag3QflrhhY3xmOTjT0pve8/rYp1O1ncW7WTUdr9r4q9wdTx9CMnhqeoHTeqObt4e7ye91bfPd047PSEFFH4feDIQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=djWGZdEG; 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="djWGZdEG" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2145DC19421; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=EIzss4+nVhmBM716ght5tv9bi2u8EXv+0cXIqsZnexs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=djWGZdEGjm9gYcPBqwD1BId5hx3PKr9WOW/SdWmMGopvT/s9r4KPIaWYZ42P3QmPe yiWYVC/WOebllm9+pH10GNUWQYEWSBHukz+fhipIlxuy8wfy5wjUHj55pYqSLMJiHR 38it1cy4s4Twd3lnlSiEODudYqo7BoRiU71oWMoRxmI+6tgdo45Khz+JyIDItTTozp uu4NiDvv7EvlCluUpP5zkNUJgfjjsSrkg7Yz79PggptS2k01fSUiI1J29NqvfguhSc zF0t8io4PvGctFMmRLaAEBXsNowUEk+0hA2ijqQNBgVn4escrv7N0DQATNRq6m1Mf0 UREfJZjywdwOA== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRMJ-1ZDu; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , Catalin Marinas , Will Deacon , linux-arm-kernel@lists.infradead.org, linux-kernel@vger.kernel.org Subject: [RFC v2 30/38] docs: arm: asymmetric-32bit: Allow creating cross-references for ABI Date: Tue, 28 Jan 2025 01:06:19 +0100 Message-ID: <88b0601a8d6e6f23fc3ad2a68b552b66df190945.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Now that Documentation/ABI is processed by automarkup, let it generate cross-references for the corresponding ABI file. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/arch/arm64/asymmetric-32bit.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/arch/arm64/asymmetric-32bit.rst b/Documentation/= arch/arm64/asymmetric-32bit.rst index 64a0b505da7d..f15061b1e020 100644 --- a/Documentation/arch/arm64/asymmetric-32bit.rst +++ b/Documentation/arch/arm64/asymmetric-32bit.rst @@ -55,7 +55,7 @@ sysfs =20 The subset of CPUs capable of running 32-bit tasks is described in ``/sys/devices/system/cpu/aarch32_el0`` and is documented further in -``Documentation/ABI/testing/sysfs-devices-system-cpu``. +Documentation/ABI/testing/sysfs-devices-system-cpu. =20 **Note:** CPUs are advertised by this file as they are detected and so late-onlining of 32-bit-capable CPUs can result in the file contents --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 7EC26383A5; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=n42gnjl4HKJ6PjdgWUYsVcdyrMPM8k0iWgd6QX0RU47VK3wgn7DAU16alMqHDUOotbYiPQtGlmDAXfH2t6+pAOk5/wjEbV8lRBjTAu+Ga9LE3Mq/IpOTM5S9kz3wO4EDIwgjGYfMOQPuen3RmDDXfXiG6/n6CpXttblW1EWu5u8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=QXk/JHBxUK/Ths9qSQMqY9AnKVsl6SgMJq6d9H2BT/U=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=VLB+FBoamkiHw9teOm5NDe8beyv2QnYpp3XxThuhU9iUCUerYIRaNCGT/BX/zeVzebvjdhWL4aK00r/uxqDeW8okOtSuQQ0hdZV1LmAqAee+R19Db3Xw8rJAj6k+4yHbMvyThAfl9xLhQIEQFoWcQBpDw4JtKOM3oJMbvR1Mwfc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=YIXLnxTN; 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="YIXLnxTN" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 465ADC2BC9E; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=QXk/JHBxUK/Ths9qSQMqY9AnKVsl6SgMJq6d9H2BT/U=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YIXLnxTNG7OUcOH0i7SRQ5lOz+0+nOzGxMUrgCJ/obzhVCbDHTnqhtjfeZwzFSWqN MOId/APnwOc3reFr+2IyuAD5B8y67Mr8zv/G/Ug8gccKFfBvQ2QodHKQ5TmTn03lMp 9OmuoVBdIBfn7Mie9wFU59bLFlBCUNeSEXzU1Xwro0iXzgpeaDDJ9T2ntHC6/2m9kC aUg/MFKUxbM+3owqFkhUtuSzAp44Ok2GhKgq6QshyWtlGCNDe0yBmd8IGfDUMCv+IH 7dty8Z5hpkaU3Pv3Mvxj9FDI91MlXz8GGlrSYCIRZ4hWN6TpgFM78Juwvi0JpflufJ G3+/dPhStHOjQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRMN-1gC4; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , William Breathitt Gray , linux-iio@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [RFC v2 31/38] docs: arm: generic-counter: Allow creating cross-references for ABI Date: Tue, 28 Jan 2025 01:06:20 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Now that Documentation/ABI is processed by automarkup, let it generate cross-references for the corresponding ABI file. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/driver-api/generic-counter.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/d= river-api/generic-counter.rst index 71ccc30e586b..e826f16ea43d 100644 --- a/Documentation/driver-api/generic-counter.rst +++ b/Documentation/driver-api/generic-counter.rst @@ -467,7 +467,7 @@ Counter sysfs Translates counter data to the standard Counter sysfs interface format and vice versa. =20 -Please refer to the ``Documentation/ABI/testing/sysfs-bus-counter`` file +Please refer to the Documentation/ABI/testing/sysfs-bus-counter file for a detailed breakdown of the available Generic Counter interface sysfs attributes. =20 @@ -483,7 +483,7 @@ Sysfs Interface Several sysfs attributes are generated by the Generic Counter interface, and reside under the ``/sys/bus/counter/devices/counterX`` directory, where ``X`` is to the respective counter device id. Please see -``Documentation/ABI/testing/sysfs-bus-counter`` for detailed information +Documentation/ABI/testing/sysfs-bus-counter for detailed information on each Generic Counter interface sysfs attribute. =20 Through these sysfs attributes, programs and scripts may interact with --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 6EA962E62B; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=uZXgMN4P3zsFvk8PmuDi0Yu76XvVkJsvFCjiuwUuTWqgV50r5Tw/aOwS/JoNmXvQV6MoEeONdJsPHGtxgJfq2FYp7qlC766J+wu6bB5VPXJSXccZAXf16WzIRbV/vtmV+q/F0SwjN7tVFvTJfYHpulOCK5r2uGcZmggsRsbMxfE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=aJ8SN/KmweREPu+e3BrG68E3yExC74uiWb70lROkL7Q=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=e23IdOE+7O6L3I/ihk6ZqdIsOcrpWNNVEzlxOueBaXfhMiFsbS+6kMBGKM37ECNgmGd4ZgVSk9qv8YTuTYo+sQNoMC5Eoan6qeLZ3yN+5IR0nm19np1X0Iize4w2r6bpvWkJ0/QZpGc47LJYMKB31F7e9kwq0kP6AnQEzvqXqnU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=E6QdLOBG; 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="E6QdLOBG" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 36367C2BCAF; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=aJ8SN/KmweREPu+e3BrG68E3yExC74uiWb70lROkL7Q=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=E6QdLOBGGkLHrxzXL7xRWh8sA571ucTDZ13JHOz81/gCmvSBA/K+cG6iGGzB+P32e ezTwKuU7l+Hu1Ob8YZKIaPTZy2ltOtHdEQKosTNlh+Hc9uuKJ0v2gJCkPP57sK41Bo jleDMqW6uyNIR59ZzzhA13UzeMTRyBMig+GYofvNJ6ge+CEPqTVbSvGOpAE6TB/MMG Xkd/1P9pn9yf4qMrHQf60K7pfgDjfaJxIpCeIt51B1LUAsxA1SnkOaxWpobqY4MGmy rzLogHiF2rpRKV/+zPYCYUFj/Vj3ERsDfJ5EZQ0EzAEcOjVcqyZgChcbF3Dt62HJ/D 5GHdv4pY5UfFA== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRMR-1nNr; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , Jonathan Cameron , Lars-Peter Clausen , Thorsten Scherer , linux-iio@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [RFC v2 32/38] docs: iio: Allow creating cross-references ABI Date: Tue, 28 Jan 2025 01:06:21 +0100 Message-ID: <71e13fab5e63de2f16d6953cc6ebf3b51f1f9f6e.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Now that Documentation/ABI is processed by automarkup, let it generate cross-references for the corresponding ABI file. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Cameron Reported-by: Akira Yokosawa --- Documentation/driver-api/iio/core.rst | 2 +- Documentation/iio/iio_devbuf.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/driver-api/iio/core.rst b/Documentation/driver-a= pi/iio/core.rst index dfe438dc91a7..42b580fb2989 100644 --- a/Documentation/driver-api/iio/core.rst +++ b/Documentation/driver-api/iio/core.rst @@ -60,7 +60,7 @@ directory. Common attributes are: * :file:`sampling_frequency_available`, available discrete set of sampling frequency values for device. * Available standard attributes for IIO devices are described in the - :file:`Documentation/ABI/testing/sysfs-bus-iio` file in the Linux kernel + :file:Documentation/ABI/testing/sysfs-bus-iio file in the Linux kernel sources. =20 IIO device channels diff --git a/Documentation/iio/iio_devbuf.rst b/Documentation/iio/iio_devbu= f.rst index 9919e4792d0e..dca1f0200b0d 100644 --- a/Documentation/iio/iio_devbuf.rst +++ b/Documentation/iio/iio_devbuf.rst @@ -148,5 +148,5 @@ applied), however there are corner cases in which the b= uffered data may be found in a processed form. Please note that these corner cases are not addressed= by this documentation. =20 -Please see ``Documentation/ABI/testing/sysfs-bus-iio`` for a complete +Please see Documentation/ABI/testing/sysfs-bus-iio for a complete description of the attributes. --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 7005B2EAE4; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=ADdvoWSiP5hoEZKqZJ7FdjwBlEWGMtWHKvY1R0dtCdH0N9CUz+8GQ536lBBiLwStvSVPiFdVSjugCnvy++HkSqAKCbHdFeAzjQjjYd+ADzsq2aAwNWbrj9Og+bMB7fyy3Yrxh60CKkkN5KBLma2jYAeCfSm8hS1tLlHMHZ2x1CY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=mcoeXqisQ9cCp+d9XJhL6+xR7Bjlo3DbBhHTGHu6E1M=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=mb/fBHiIn11oNChQoP4ONXrzQiIIdYy9kgXojCXa/+fkHGXpdCqfv+KaonmTv4ajvYZ7mZbtFEVrSKj/XdqJpifzCjmJi9DTYlCMDfEJxEv+lDFfyU9mmBlc7ZAogryI6LjZAmFe70LoaVzEWgM1cyf0KHNSSaHFs92t/MFeqbs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=i/GkfumJ; 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="i/GkfumJ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 34C85C2BC87; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=mcoeXqisQ9cCp+d9XJhL6+xR7Bjlo3DbBhHTGHu6E1M=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=i/GkfumJbBhJUTjl4JTzh/iy8mfn9/It3WkKIu3zIlKWvHu0EAtF6V0KNiHIp6yH+ Nl7g3XMYh8T3nAZDYNTH4IsWgzt3chE87YqXd9u+uF18FfHV35y8NvD8p6a4RbE+sy 3P+PnnEql66gkIKL5eGyr2s8R9MZenErrYRqiDBFrVt/BTZQiZPQlq4f7gUAQGt9Su 6QQlsVsVL+nWBVxAkWsloMmi14Efc7VQYDoPiq7r9NTXDpiMLlS+9mIG48m1OcT5tc ERR8Y/O25a9SGMYM29Wzs5i9jD1k9509j8EMqpHiyXffA3pUqaF/8xbgsh/68tUDkc FZas3WZRc/ePw== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRMW-1ubB; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "David S. Miller" , "Mauro Carvalho Chehab" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , Simon Horman , linux-kernel@vger.kernel.org, netdev@vger.kernel.org Subject: [RFC v2 33/38] docs: networking: Allow creating cross-references statistics ABI Date: Tue, 28 Jan 2025 01:06:22 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Now that Documentation/ABI is processed by automarkup, let it generate cross-references for the corresponding ABI file. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/networking/statistics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/networking/statistics.rst b/Documentation/networ= king/statistics.rst index 75e017dfa825..518284e287b0 100644 --- a/Documentation/networking/statistics.rst +++ b/Documentation/networking/statistics.rst @@ -143,7 +143,7 @@ reading multiple stats as it internally performs a full= dump of and reports only the stat corresponding to the accessed file. =20 Sysfs files are documented in -`Documentation/ABI/testing/sysfs-class-net-statistics`. +Documentation/ABI/testing/sysfs-class-net-statistics. =20 =20 netlink --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 871E53BBF0; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=tBVGvWeTIzLEZ3YUceDp4JM00xRnNzAszPrONSf9xlQc4SIStzxvjap7H6lfbDZ6CQCwvSptGBWml7Pp10gHDNVmGtE8oLGgvvtOcQLBEkcsaJdOd/+sVb9/yjkHRIDmJEr5o7A4r3VCOqW2HERSoTpcGbTIIOFNJvKhQ+Dsta8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=lhhjW4xvN5/JBeiDA+D11vVkCEKozoutHtedahprF+M=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=IfGAt4ARqVLO0WUbOzsOkL2SAJ4JsYPNspgEOIo6Q9m4vrF/zh6V781eJ4tQ8PYeT74iSBBz05FOAqhm7XAYnscDuwsrRjFQR36YIn+t4rgEbZFv8mGNmsWSo9nuN4hb3PYa8GtvM9svNNpfqkYhzKZXmrb9ThDxS7H1JFz8/Vw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=PUuYd/js; 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="PUuYd/js" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5C65DC4AF19; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=lhhjW4xvN5/JBeiDA+D11vVkCEKozoutHtedahprF+M=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PUuYd/jsQG21oCXIUvWXaM+i5S/AFRRfYcDM0Nmtf5pd9XH6kCIyHxASgZ2NQXi8o ocDDJp0o4069shKBMazBjRbQZc5Y5ZYWcM/rrfjMFXWAGwmLlPJz/Jr++1i1ThIBDY aCKSau/eb18BgycvmhRDFWry5YwVetB2P/ymyXXLD0+zOfvN7yOfHFJ+4nlPH0Qcgu VEgDljYtUb7AC1D3jgik17gKbN/VY2OxoXM2L2ykE3xzrEKNzxHcNQI+F/Q74UeK8O XEgozCpHJz0TvJHOnWzWeWhqB/mvwqP9Z+kW7q2k7AnWYHSwKkRf78Fbytufmb6p1r xE0e6r6vCAA8A== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRMb-21eU; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org, workflows@vger.kernel.org Subject: [RFC v2 34/38] docs: submit-checklist: Allow creating cross-references for ABI README Date: Tue, 28 Jan 2025 01:06:23 +0100 Message-ID: <94b906a3806c667e69b41879fe77e100aaedc917.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Now that Documentation/ABI is processed by automarkup, let it generate cross-references for the ABI README file. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/process/submit-checklist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/process/submit-checklist.rst b/Documentation/pro= cess/submit-checklist.rst index e531dd504b6c..827566872567 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -52,7 +52,7 @@ Provide documentation 4) All new module parameters are documented with ``MODULE_PARM_DESC()`` =20 5) All new userspace interfaces are documented in ``Documentation/ABI/``. - See ``Documentation/ABI/README`` for more information. + See Documentation/ABI/README for more information. Patches that change userspace interfaces should be CCed to linux-api@vger.kernel.org. =20 --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 88F473F9D2; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=Vptj5izVXhE7R8Wt2lcjk7t0PemL6Kj5fns7sxvFCeeDKd6OegGBxkICaLhjgA/6erFNacnK1kOhrfJfDmak/16EGV1K79YRfUYhB/J4qcYTADZfqquwTkKCu3VvIUK3PiUC6bUCNR8OoyEE0JHnPcn7M930VRcz1lbLJZuMcrI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=xJJNTHLm28pOieLtRLXBCsjINp9HkQQLtgWkMVSB5X4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=I5kNETZOx5EVGaAD5b7jRzOrQeoPwpYmN2277RTpie6q06fR3W7OYK6XrQDjJBew28Qo//o7YaqRlXWlnp/FXpbnuT76O4UD3s9xjJoT5W7ZpExhFkc8UTf6agsWpuj+hWBegE3sYhcskbdtpuutUY6txTKdKkkXa8+SSTDOjeE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=jZQ9ElEe; 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="jZQ9ElEe" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5C351C2BCC9; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=xJJNTHLm28pOieLtRLXBCsjINp9HkQQLtgWkMVSB5X4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jZQ9ElEe+UoE3g3WSMWUU1bwfgG6y/RTF9cicxaYybx4nRoWeP4NVh+HgpYQ7tkw2 +2iMuquNOku20W1CadQA/Np5pNpqoOhFrMyJ9G6UlaQuLyltTs2PWNPKnmrvTgHhTa sDl/PUJWhMjzh3OSbZy9VxKzqxaay8gdAQnDeUS1Ziaz+T1CAZdbR2/16yeIMJZiRm 3/o0L4T/bvvKm99q/YaOA8aCTLnBpGN4xFcBz2gNqXTrPtStbQ36pQtr2dwtrzq6AB PuHlURRqO3U0yCSvs90vewtVSwgIBrmfQLWzXXXqa/vDBI3hyZEGbn/941S3p6qa3u 41uOZKM3Enskg== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRMg-28Vv; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , Alex Shi , Avadhut Naik , Carlos Bilbao , Federico Vaga , Hu Haowen <2023002089@link.tyut.edu.cn>, Randy Dunlap , Remington Brasga , Yanteng Si , linux-kernel@vger.kernel.org Subject: [RFC v2 35/38] docs: translations: Allow creating cross-references for ABI README Date: Tue, 28 Jan 2025 01:06:24 +0100 Message-ID: <2699a7eeb90f0a3c419928fbf696339637b02463.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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 Update translations to also generate cross references for the ABI readme file. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/translations/it_IT/process/submit-checklist.rst | 2 +- Documentation/translations/sp_SP/process/submit-checklist.rst | 2 +- Documentation/translations/zh_CN/process/submit-checklist.rst | 2 +- Documentation/translations/zh_TW/process/submit-checklist.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/translations/it_IT/process/submit-checklist.rst = b/Documentation/translations/it_IT/process/submit-checklist.rst index 692be4af9c9b..3308c3084c60 100644 --- a/Documentation/translations/it_IT/process/submit-checklist.rst +++ b/Documentation/translations/it_IT/process/submit-checklist.rst @@ -58,7 +58,7 @@ Fornite documentazione 4) Tutti i nuovi parametri dei moduli sono documentati con ``MODULE_PARM_D= ESC()``. =20 5) Tutte le nuove interfacce verso lo spazio utente sono documentate in - ``Documentation/ABI/``. Leggete ``Documentation/ABI/README`` per magg= iori + ``Documentation/ABI/``. Leggete Documentation/ABI/README per maggiori informazioni. Le patch che modificano le interfacce utente dovrebbero essere inviate in copia anche a linux-api@vger.kernel.org. =20 diff --git a/Documentation/translations/sp_SP/process/submit-checklist.rst = b/Documentation/translations/sp_SP/process/submit-checklist.rst index 0d6651f9d871..3087ba80e818 100644 --- a/Documentation/translations/sp_SP/process/submit-checklist.rst +++ b/Documentation/translations/sp_SP/process/submit-checklist.rst @@ -97,7 +97,7 @@ y en otros lugares con respecto al env=C3=ADo de parches = del kernel de Linux. ``MODULE_PARM_DESC()``. =20 18) Todas las nuevas interfaces de espacio de usuario est=C3=A1n documenta= das - en ``Documentation/ABI/``. Consulte ``Documentation/ABI/README`` para + en ``Documentation/ABI/``. Consulte Documentation/ABI/README para obtener m=C3=A1s informaci=C3=B3n. Los parches que cambian las interfa= ces del espacio de usuario deben ser CCed a linux-api@vger.kernel.org. =20 diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst = b/Documentation/translations/zh_CN/process/submit-checklist.rst index 10536b74aeec..5c20a7f0936b 100644 --- a/Documentation/translations/zh_CN/process/submit-checklist.rst +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst @@ -82,7 +82,7 @@ Linux=E5=86=85=E6=A0=B8=E8=A1=A5=E4=B8=81=E6=8F=90=E4=BA= =A4=E6=A3=80=E6=9F=A5=E5=8D=95 17) =E6=89=80=E6=9C=89=E6=96=B0=E7=9A=84=E6=A8=A1=E5=9D=97=E5=8F=82=E6=95= =B0=E9=83=BD=E8=AE=B0=E5=BD=95=E5=9C=A8 ``MODULE_PARM_DESC()`` =20 18) =E6=89=80=E6=9C=89=E6=96=B0=E7=9A=84=E7=94=A8=E6=88=B7=E7=A9=BA=E9=97= =B4=E6=8E=A5=E5=8F=A3=E9=83=BD=E8=AE=B0=E5=BD=95=E5=9C=A8 ``Documentation/A= BI/`` =E4=B8=AD=E3=80=82=E6=9C=89=E5=85=B3=E8=AF=A6=E7=BB=86=E4=BF=A1=E6=81= =AF=EF=BC=8C - =E8=AF=B7=E5=8F=82=E9=98=85 ``Documentation/ABI/README`` =E3=80=82=E6= =9B=B4=E6=94=B9=E7=94=A8=E6=88=B7=E7=A9=BA=E9=97=B4=E6=8E=A5=E5=8F=A3=E7=9A= =84=E8=A1=A5=E4=B8=81=E5=BA=94=E8=AF=A5=E6=8A=84=E9=80=81 + =E8=AF=B7=E5=8F=82=E9=98=85 Documentation/ABI/README =E3=80=82=E6=9B= =B4=E6=94=B9=E7=94=A8=E6=88=B7=E7=A9=BA=E9=97=B4=E6=8E=A5=E5=8F=A3=E7=9A=84= =E8=A1=A5=E4=B8=81=E5=BA=94=E8=AF=A5=E6=8A=84=E9=80=81 linux-api@vger.kernel.org=E3=80=82 =20 19) =E5=B7=B2=E9=80=9A=E8=BF=87=E8=87=B3=E5=B0=91=E6=B3=A8=E5=85=A5slab=E5= =92=8Cpage=E5=88=86=E9=85=8D=E5=A4=B1=E8=B4=A5=E8=BF=9B=E8=A1=8C=E6=A3=80= =E6=9F=A5=E3=80=82=E8=AF=B7=E5=8F=82=E9=98=85 ``Documentation/fault-injecti= on/`` =E3=80=82 diff --git a/Documentation/translations/zh_TW/process/submit-checklist.rst = b/Documentation/translations/zh_TW/process/submit-checklist.rst index 0ecb187753e4..b09d29b0cc1b 100644 --- a/Documentation/translations/zh_TW/process/submit-checklist.rst +++ b/Documentation/translations/zh_TW/process/submit-checklist.rst @@ -85,7 +85,7 @@ Linux=E5=85=A7=E6=A0=B8=E8=A3=9C=E4=B8=81=E6=8F=90=E4=BA= =A4=E6=AA=A2=E6=9F=A5=E5=96=AE 17) =E6=89=80=E6=9C=89=E6=96=B0=E7=9A=84=E6=A8=A1=E5=A1=8A=E5=8F=83=E6=95= =B8=E9=83=BD=E8=A8=98=E9=8C=84=E5=9C=A8 ``MODULE_PARM_DESC()`` =20 18) =E6=89=80=E6=9C=89=E6=96=B0=E7=9A=84=E7=94=A8=E6=88=B6=E7=A9=BA=E9=96= =93=E6=8E=A5=E5=8F=A3=E9=83=BD=E8=A8=98=E9=8C=84=E5=9C=A8 ``Documentation/A= BI/`` =E4=B8=AD=E3=80=82=E6=9C=89=E9=97=9C=E8=A9=B3=E7=B4=B0=E4=BF=A1=E6=81= =AF=EF=BC=8C - =E8=AB=8B=E5=8F=83=E9=96=B1 ``Documentation/ABI/README`` =E3=80=82=E6= =9B=B4=E6=94=B9=E7=94=A8=E6=88=B6=E7=A9=BA=E9=96=93=E6=8E=A5=E5=8F=A3=E7=9A= =84=E8=A3=9C=E4=B8=81=E6=87=89=E8=A9=B2=E6=8A=84=E9=80=81 + =E8=AB=8B=E5=8F=83=E9=96=B1 Documentation/ABI/README =E3=80=82=E6=9B= =B4=E6=94=B9=E7=94=A8=E6=88=B6=E7=A9=BA=E9=96=93=E6=8E=A5=E5=8F=A3=E7=9A=84= =E8=A3=9C=E4=B8=81=E6=87=89=E8=A9=B2=E6=8A=84=E9=80=81 linux-api@vger.kernel.org=E3=80=82 =20 19) =E5=B7=B2=E9=80=9A=E9=81=8E=E8=87=B3=E5=B0=91=E6=B3=A8=E5=85=A5slab=E5= =92=8Cpage=E5=88=86=E9=85=8D=E5=A4=B1=E6=95=97=E9=80=B2=E8=A1=8C=E6=AA=A2= =E6=9F=A5=E3=80=82=E8=AB=8B=E5=8F=83=E9=96=B1 ``Documentation/fault-injecti= on/`` =E3=80=82 --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 8723F3D561; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=P2QZ9l8cMOpMaoHwsvZ5NgNrbcee1Owwz94KGP22zfWZKZxtgeXSh+7+uV+H84HeAZQe+F8Wknx25Plsh5QTO8SDBDjGYrXp+c+EntpB4I03qrzwW26PfYUM/xbDbn+Hg1U5pmHzCp6aR9fwDh0UMSXrX7lcanBR37p9D0KpCBQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=ZlYS8/RGksFoYa5QMgx8JgmK5kqKi2Lgph+Ezj5n8ss=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=XSKS3J1vLdzVDuQvqI4aWdUZFGhXilLPwjeOMjD96aTHB52h+BnsIigvSCbBodaXUi7hBjrBazsaXz7WqYaD6ukeIfyoy7jbAjxp+1D/AB9Z4YTJrSP8u+MhSWJsiRFyw28OEfH2J9TJtJ/607m0GLCmUiN1MKU96+qGGH7gGBc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=nI90iYlc; 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="nI90iYlc" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4DE32C4AF18; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=ZlYS8/RGksFoYa5QMgx8JgmK5kqKi2Lgph+Ezj5n8ss=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nI90iYlcLydzPEo7oi3Q9W9EddFrzp4G1Ae9CdRiAD/6vapq3z450BmV6vSkDdDYs kuYR2iwFak2woWBn1o5MnP2tTdJ4j1ssVNr59xHACzj0h50PWrAz+SkFazSAEMx8i5 67c0FnqNifnCrqMsx8URUspZIeD0kuLY2n9EK21IUmXxqyEnmJQ+PbxMdluaWbZgcM oNW8pfk0+g0C6sSsxRu1kmNbEFP4lKK1aZTGnz5TJ0ndm5au/fINspJtSQVWOfXaR/ 8EqXVHntvzmPMJYqrzsjxLtkD6kCYwKdpYx0Y1VnPVM/CzPBHsprTsCVhlMA4bdV8d YjSEzBwIgoaoQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRMk-2FW0; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [RFC v2 36/38] docs: ABI: drop two duplicate symbols Date: Tue, 28 Jan 2025 01:06:25 +0100 Message-ID: <673e9543783349b0fcf625018e38e4e93fe98f52.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" As warned by get_abi.py, there are two symbols that are defined twice: WARNING: /sys/devices/system/cpu/cpuX/topology/physical_package_id is defin= ed 2 times: \ /new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:27; \ /new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70 WARNING: /sys/devices/system/cpu/cpuX/topology/ppin is defined 2 times: \ /new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:89; \ /new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70 As the documentation at testing/sysfs-devices-system-cpu, drop the duplicated one from stable. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- Documentation/ABI/stable/sysfs-devices-system-cpu | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/Documentation/ABI/stable/sysfs-devices-system-cpu b/Documentat= ion/ABI/stable/sysfs-devices-system-cpu index 902392d7eddf..cf78bd99f6c8 100644 --- a/Documentation/ABI/stable/sysfs-devices-system-cpu +++ b/Documentation/ABI/stable/sysfs-devices-system-cpu @@ -24,12 +24,6 @@ Description: Default value for the Data Stream Control R= egister (DSCR) on If set by a process it will be inherited by child processes. Values: 64 bit unsigned integer (bit field) =20 -What: /sys/devices/system/cpu/cpuX/topology/physical_package_id -Description: physical package id of cpuX. Typically corresponds to a ph= ysical - socket number, but the actual value is architecture and pl= atform - dependent. -Values: integer - What: /sys/devices/system/cpu/cpuX/topology/die_id Description: the CPU die ID of cpuX. Typically it is the hardware platf= orm's identifier (rather than the kernel's). The actual value is @@ -86,10 +80,6 @@ What: /sys/devices/system/cpu/cpuX/topology/di= e_cpus Description: internal kernel map of CPUs within the same die. Values: hexadecimal bitmask. =20 -What: /sys/devices/system/cpu/cpuX/topology/ppin -Description: per-socket protected processor inventory number -Values: hexadecimal. - What: /sys/devices/system/cpu/cpuX/topology/die_cpus_list Description: human-readable list of CPUs within the same die. The format is like 0-3, 8-11, 14,17. --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 8D5BC3FBB3; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; cv=none; b=FBBHA1wWkuO7TrAJs8dU6/DDVtY9J1HGDcpFCfzxVuxhsQCUqBIqJ4ZJbexRx2ZAqUSqjhQU+1s/sIfj8Ace/K1ifAN1+GSFM+u3lxFruE1kljphOmJT+24jb/PtMoqmt9DB+hUkaaciuM712KXbQf1gwwQ2n4E24eTuCX/t3fo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022797; c=relaxed/simple; bh=3ES+UMqW9IDjhgp9zbK7Yt0ICLLMVND8zdIhJ7yDAJA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=jC5PjZULApH7XDnNyofHhtjz1rNQgmxCbbpXQZhv01z2GR5iJ/lJpRrevRlz4UX11a+foahtjwrH9Wf0VxDMYR9FpBch45MoT4HGHf5VuVtAb9LpZgK7k15ughk8NP0MNThoiEQUej6vHVX9WncIOsb+azkyQRBM3fO60IYInoA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=t44AqHzj; 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="t44AqHzj" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5349AC2BCB9; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=3ES+UMqW9IDjhgp9zbK7Yt0ICLLMVND8zdIhJ7yDAJA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=t44AqHzjYzWj3ShvYJgAzqA9/rqp4BdIqGq/Zl0qKsT0bbxwGqWSCszF8OELHkfJu eda7fNOmYrNVxX1KapzOGLsDWCefqiGpQGV2Tuodu2q1w4qF4MilPc3fjEylno1zsG KA42SgMtHCyCiHt5HPDsGDE3ERpTQcYtxNQ5g7Qe16ZJSwROv/p7hK6W1A+E+SIQSO ugN1GrzbQfMhBAAbMEZj1k3V/RcWtaJ7+haG4YI68BY+uGKS0kCyAtS4bHUwLt/V5h HhFrGGC2sOBEVnyKl8iQVHJBxiO1beQryJ+vdt8pq/vcmPUj6QnwRtTwc/au9vxzjG UaUtv9tvINZIQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRMo-2MV1; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Guilherme G. Piccoli" , "Mauro Carvalho Chehab" , Kees Cook , Tony Luck , bpf@vger.kernel.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [RFC v2 37/38] scripts/get_abi.py: add support for undefined ABIs Date: Tue, 28 Jan 2025 01:06:26 +0100 Message-ID: <6ae44b8acd09b8fc14a7824a42ab42faa4e96f8d.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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 undefined logic is complex and has lots of magic on it. Implement it, using the same algorithm we have at get_abi.pl. Yet, some tweaks to optimize performance and to make the code simpler were added here: - at the perl version, the tree graph had loops, so we had to use BFS to traverse it. On this version, the graph is a tree, so, it simplifies the what group for sysfs aliases; - the logic which splits regular expressions into subgroups was re-written to make it faster; - it may optionally use multiple processes to search for symbol matches; - it has some additional debug levels. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- scripts/get_abi.py | 670 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 669 insertions(+), 1 deletion(-) diff --git a/scripts/get_abi.py b/scripts/get_abi.py index 1c9c6b23a6fb..543bed397c8c 100755 --- a/scripts/get_abi.py +++ b/scripts/get_abi.py @@ -13,8 +13,10 @@ import os import re import sys =20 +from concurrent import futures from pprint import pformat -from random import randrange, seed +from random import randrange, seed, shuffle +from datetime import datetime =20 ABI_DIR =3D "Documentation/ABI/" =20 @@ -22,6 +24,12 @@ ABI_DIR =3D "Documentation/ABI/" DEBUG_WHAT_PARSING =3D 1 DEBUG_WHAT_OPEN =3D 2 DEBUG_DUMP_ABI_STRUCTS =3D 4 +DEBUG_UNDEFINED =3D 8 +DEBUG_REGEX =3D 16 +DEBUG_SUBGROUP_MAP =3D 32 +DEBUG_SUBGROUP_DICT =3D 64 +DEBUG_SUBGROUP_SIZE =3D 128 +DEBUG_GRAPH =3D 256 =20 DEBUG_HELP =3D """ Print debug information according with the level(s), @@ -30,6 +38,13 @@ which is given by the following bitmask: 1 - enable debug parsing logic 2 - enable debug messages on file open 4 - enable debug for ABI parse data +8 - enable extra debug information to identify troubles + with ABI symbols found at the local machine that + weren't found on ABI documentation (used only for + undefined subcommand) +16 - enable debug for what to regex conversion +32 - enable debug for symbol regex subgroups +64 - enable debug for sysfs graph tree variable """ =20 =20 @@ -638,6 +653,593 @@ class AbiParser: print(f"Regular expression /{expr}/ not found.") =20 =20 +class AbiRegex(AbiParser): + """Extends AbiParser to search ABI nodes with regular expressions""" + + # Escape only ASCII visible characters + escape_symbols =3D r"([\x21-\x29\x2b-\x2d\x3a-\x40\x5c\x60\x7b-\x7e])" + leave_others =3D "others" + + # Tuples with regular expressions to be compiled and replacement data + re_whats =3D [ + # Drop escape characters that might exist + (re.compile("\\\\"), ""), + + # Temporarily escape dot characters + (re.compile(r"\."), "\xf6"), + + # Temporarily change [0-9]+ type of patterns + (re.compile(r"\[0\-9\]\+"), "\xff"), + + # Temporarily change [\d+-\d+] type of patterns + (re.compile(r"\[0\-\d+\]"), "\xff"), + (re.compile(r"\[0:\d+\]"), "\xff"), + (re.compile(r"\[(\d+)\]"), "\xf4\\\\d+\xf5"), + + # Temporarily change [0-9] type of patterns + (re.compile(r"\[(\d)\-(\d)\]"), "\xf4\1-\2\xf5"), + + # Handle multiple option patterns + (re.compile(r"[\{\<\[]([\w_]+)(?:[,|]+([\w_]+)){1,}[\}\>\]]"), r"(= \1|\2)"), + + # Handle wildcards + (re.compile(r"([^\/])\*"), "\\1\\\\w\xf7"), + (re.compile(r"/\*/"), "/.*/"), + (re.compile(r"/\xf6\xf6\xf6"), "/.*"), + (re.compile(r"\<[^\>]+\>"), "\\\\w\xf7"), + (re.compile(r"\{[^\}]+\}"), "\\\\w\xf7"), + (re.compile(r"\[[^\]]+\]"), "\\\\w\xf7"), + + (re.compile(r"XX+"), "\\\\w\xf7"), + (re.compile(r"([^A-Z])[XYZ]([^A-Z])"), "\\1\\\\w\xf7\\2"), + (re.compile(r"([^A-Z])[XYZ]$"), "\\1\\\\w\xf7"), + (re.compile(r"_[AB]_"), "_\\\\w\xf7_"), + + # Recover [0-9] type of patterns + (re.compile(r"\xf4"), "["), + (re.compile(r"\xf5"), "]"), + + # Remove duplicated spaces + (re.compile(r"\s+"), r" "), + + # Special case: drop comparison as in: + # What: foo =3D + # (this happens on a few IIO definitions) + (re.compile(r"\s*\=3D.*$"), ""), + + # Escape all other symbols + (re.compile(escape_symbols), r"\\\1"), + (re.compile(r"\\\\"), r"\\"), + (re.compile(r"\\([\[\]\(\)\|])"), r"\1"), + (re.compile(r"(\d+)\\(-\d+)"), r"\1\2"), + + (re.compile(r"\xff"), r"\\d+"), + + # Special case: IIO ABI which a parenthesis. + (re.compile(r"sqrt(.*)"), r"sqrt(.*)"), + + # Simplify regexes with multiple .* + (re.compile(r"(?:\.\*){2,}"), ""), + + # Recover dot characters + (re.compile(r"\xf6"), "\\."), + # Recover plus characters + (re.compile(r"\xf7"), "+"), + ] + re_has_num =3D re.compile(r"\\d") + + # Symbol name after escape_chars that are considered a devnode basename + re_symbol_name =3D re.compile(r"(\w|\\[\.\-\:])+$") + + # List of popular group names to be skipped to minimize regex group si= ze + # Use DEBUG_SUBGROUP_SIZE to detect those + skip_names =3D set(["devices", "hwmon"]) + + def regex_append(self, what, new): + """ + Get a search group for a subset of regular expressions. + + As ABI may have thousands of symbols, using a for to search all + regular expressions is at least O(n^2). When there are wildcards, + the complexity increases substantially, eventually becoming expone= ntial. + + To avoid spending too much time on them, use a logic to split + them into groups. The smaller the group, the better, as it would + mean that searches will be confined to a small number of regular + expressions. + + The conversion to a regex subset is tricky, as we need something + that can be easily obtained from the sysfs symbol and from the + regular expression. So, we need to discard nodes that have + wildcards. + + If it can't obtain a subgroup, place the regular expression inside + a special group (self.leave_others). + """ + + for search_group in reversed(new.split("/")): + if not search_group or search_group in self.skip_names: + continue + if self.re_symbol_name.match(search_group): + break + + if not search_group: + search_group =3D self.leave_others + + if self.debug & DEBUG_SUBGROUP_MAP: + self.log.debug("%s: mapped as %s", what, search_group) + + try: + if search_group not in self.regex_group: + self.regex_group[search_group] =3D [] + + self.regex_group[search_group].append(re.compile(new)) + if self.search_string: + if what.find(self.search_string) >=3D 0: + print(f"What: {what}") + except re.PatternError: + self.log.warning("Ignoring '%s' as it produced an invalid rege= x:\n" + " '%s'", what, new) + + def get_regexes(self, what): + """ + Given an ABI devnode, return a list of all regular expressions that + may match it, based on the sub-groups created by regex_append() + """ + + re_list =3D [] + + patches =3D what.split("/") + patches.reverse() + patches.append(self.leave_others) + + for search_group in patches: + if search_group in self.regex_group: + re_list +=3D self.regex_group[search_group] + + return re_list + + def __init__(self, *args, **kwargs): + """ + Override init method to get verbose argument + """ + + self.regex_group =3D None + self.search_string =3D None + self.re_string =3D None + + if "search_string" in kwargs: + self.search_string =3D kwargs.get("search_string") + del kwargs["search_string"] + + if self.search_string: + + try: + self.re_string =3D re.compile(self.search_string) + except re.PatternError as e: + msg =3D f"{self.search_string} is not a valid regular = expression" + raise ValueError(msg) from e + + super().__init__(*args, **kwargs) + + def parse_abi(self, *args, **kwargs): + + super().parse_abi(*args, **kwargs) + + self.regex_group =3D {} + + print("Converting ABI What fields into regexes...", file=3Dsys.std= err) + + for t in sorted(self.data.items(), key=3Dlambda x: x[0]): + v =3D t[1] + if v.get("type") =3D=3D "File": + continue + + v["regex"] =3D [] + + for what in v.get("what", []): + if not what.startswith("/sys"): + continue + + new =3D what + for r, s in self.re_whats: + try: + new =3D r.sub(s, new) + except re.PatternError as e: + # Help debugging troubles with new regexes + raise re.PatternError(f"{e}\nwhile re.sub('{r.patt= ern}', {s}, str)") from e + + v["regex"].append(new) + + if self.debug & DEBUG_REGEX: + self.log.debug("%-90s <=3D=3D %s", new, what) + + # Store regex into a subgroup to speedup searches + self.regex_append(what, new) + + if self.debug & DEBUG_SUBGROUP_DICT: + self.log.debug("%s", pformat(self.regex_group)) + + if self.debug & DEBUG_SUBGROUP_SIZE: + biggestd_keys =3D sorted(self.regex_group.keys(), + key=3D lambda k: len(self.regex_group[k= ]), + reverse=3DTrue) + + print("Top regex subgroups:", file=3Dsys.stderr) + for k in biggestd_keys[:10]: + print(f"{k} has {len(self.regex_group[k])} elements", file= =3Dsys.stderr) + +class SystemSymbols: + """Stores arguments for the class and initialize class vars""" + + def graph_add_file(self, path, link=3DNone): + """ + add a file path to the sysfs graph stored at self.root + """ + + if path in self.files: + return + + name =3D "" + ref =3D self.root + for edge in path.split("/"): + name +=3D edge + "/" + if edge not in ref: + ref[edge] =3D {"__name": [name.rstrip("/")]} + + ref =3D ref[edge] + + if link and link not in ref["__name"]: + ref["__name"].append(link.rstrip("/")) + + self.files.add(path) + + def print_graph(self, root_prefix=3D"", root=3DNone, level=3D0): + """Prints a reference tree graph using UTF-8 characters""" + + if not root: + root =3D self.root + level =3D 0 + + # Prevent endless traverse + if level > 5: + return + + if level > 0: + prefix =3D "=E2=94=9C=E2=94=80=E2=94=80" + last_prefix =3D "=E2=94=94=E2=94=80=E2=94=80" + else: + prefix =3D "" + last_prefix =3D "" + + items =3D list(root.items()) + + names =3D root.get("__name", []) + for k, edge in items: + if k =3D=3D "__name": + continue + + if not k: + k =3D "/" + + if len(names) > 1: + k +=3D " links: " + ",".join(names[1:]) + + if edge =3D=3D items[-1][1]: + print(root_prefix + last_prefix + k) + p =3D root_prefix + if level > 0: + p +=3D " " + self.print_graph(p, edge, level + 1) + else: + print(root_prefix + prefix + k) + p =3D root_prefix + "=E2=94=82 " + self.print_graph(p, edge, level + 1) + + def _walk(self, root): + """ + Walk through sysfs to get all devnodes that aren't ignored. + + By default, uses /sys as sysfs mounting point. If another + directory is used, it replaces them to /sys at the patches. + """ + + with os.scandir(root) as obj: + for entry in obj: + path =3D os.path.join(root, entry.name) + if self.sysfs: + p =3D path.replace(self.sysfs, "/sys", count=3D1) + else: + p =3D path + + if self.re_ignore.search(p): + return + + # Handle link first to avoid directory recursion + if entry.is_symlink(): + real =3D os.path.realpath(path) + if not self.sysfs: + self.aliases[path] =3D real + else: + real =3D real.replace(self.sysfs, "/sys", count=3D= 1) + + # Add absfile location to graph if it doesn't exist + if not self.re_ignore.search(real): + # Add link to the graph + self.graph_add_file(real, p) + + elif entry.is_file(): + self.graph_add_file(p) + + elif entry.is_dir(): + self._walk(path) + + def __init__(self, abi, sysfs=3D"/sys", hints=3DFalse): + """ + Initialize internal variables and get a list of all files inside + sysfs that can currently be parsed. + + Please notice that there are several entries on sysfs that aren't + documented as ABI. Ignore those. + + The real paths will be stored under self.files. Aliases will be + stored in separate, as self.aliases. + """ + + self.abi =3D abi + self.log =3D abi.log + + if sysfs !=3D "/sys": + self.sysfs =3D sysfs.rstrip("/") + else: + self.sysfs =3D None + + self.hints =3D hints + + self.root =3D {} + self.aliases =3D {} + self.files =3D set() + + dont_walk =3D [ + # Those require root access and aren't documented at ABI + f"^{sysfs}/kernel/debug", + f"^{sysfs}/kernel/tracing", + f"^{sysfs}/fs/pstore", + f"^{sysfs}/fs/bpf", + f"^{sysfs}/fs/fuse", + + # This is not documented at ABI + f"^{sysfs}/module", + + f"^{sysfs}/fs/cgroup", # this is big and has zero docs under = ABI + f"^{sysfs}/firmware", # documented elsewhere: ACPI, DT bindi= ngs + "sections|notes", # aren't actually part of ABI + + # kernel-parameters.txt - not easy to parse + "parameters", + ] + + self.re_ignore =3D re.compile("|".join(dont_walk)) + + print(f"Reading {sysfs} directory contents...", file=3Dsys.stderr) + self._walk(sysfs) + + def check_file(self, refs, found): + """Check missing ABI symbols for a given sysfs file""" + + res_list =3D [] + + try: + for names in refs: + fname =3D names[0] + + res =3D { + "found": False, + "fname": fname, + "msg": "", + } + res_list.append(res) + + re_what =3D self.abi.get_regexes(fname) + if not re_what: + self.abi.log.warning(f"missing rules for {fname}") + continue + + for name in names: + for r in re_what: + if self.abi.debug & DEBUG_UNDEFINED: + self.log.debug("check if %s matches '%s'", nam= e, r.pattern) + if r.match(name): + res["found"] =3D True + if found: + res["msg"] +=3D f" {fname}: regex:\n\t" + continue + + if self.hints and not res["found"]: + res["msg"] +=3D f" {fname} not found. Tested regexes:= \n" + for r in re_what: + res["msg"] +=3D " " + r.pattern + "\n" + + except KeyboardInterrupt: + pass + + return res_list + + def _ref_interactor(self, root): + """Recursive function to interact over the sysfs tree""" + + for k, v in root.items(): + if isinstance(v, dict): + yield from self._ref_interactor(v) + + if root =3D=3D self.root or k =3D=3D "__name": + continue + + if self.abi.re_string: + fname =3D v["__name"][0] + if self.abi.re_string.search(fname): + yield v + else: + yield v + + + def get_fileref(self, all_refs, chunk_size): + """Interactor to group refs into chunks""" + + n =3D 0 + refs =3D [] + + for ref in all_refs: + refs.append(ref) + + n +=3D 1 + if n >=3D chunk_size: + yield refs + n =3D 0 + refs =3D [] + + yield refs + + def check_undefined_symbols(self, max_workers=3DNone, chunk_size=3D50, + found=3DNone, dry_run=3DNone): + """Seach ABI for sysfs symbols missing documentation""" + + self.abi.parse_abi() + + if self.abi.debug & DEBUG_GRAPH: + self.print_graph() + + all_refs =3D [] + for ref in self._ref_interactor(self.root): + all_refs.append(ref["__name"]) + + if dry_run: + print(f"Would check", file=3Dsys.stderr) + for ref in all_refs: + print(", ".join(ref)) + + return + + print("Starting to search symbols (it may take several minutes):", + file=3Dsys.stderr) + start =3D datetime.now() + old_elapsed =3D None + + # Python doesn't support multithreading due to limitations on its + # global lock (GIL). While Python 3.13 finally made GIL optional, + # there are still issues related to it. Also, we want to have + # backward compatibility with older versions of Python. + # + # So, use instead multiprocess. However, Python is very slow passi= ng + # data from/to multiple processes. Also, it may consume lots of me= mory + # if the data to be shared is not small. So, we need to group wor= kload + # in chunks that are big enough to generate performance gains while + # not being so big that would cause out-of-memory. + + num_refs =3D len(all_refs) + print(f"Number of references to parse: {num_refs}", file=3Dsys.std= err) + + if not max_workers: + max_workers =3D os.cpu_count() + elif max_workers > os.cpu_count(): + max_workers =3D os.cpu_count() + + max_workers =3D max(max_workers, 1) + + max_chunk_size =3D int((num_refs + max_workers - 1) / max_workers) + chunk_size =3D min(chunk_size, max_chunk_size) + chunk_size =3D max(1, chunk_size) + + if max_workers > 1: + executor =3D futures.ProcessPoolExecutor + + # Place references in a random order. This may help improving + # performance, by mixing complex/simple expressions when creat= ing + # chunks + shuffle(all_refs) + else: + # Python has a high overhead with processes. When there's just + # one worker, it is faster to not create a new process. + # Yet, User still deserves to have a progress print. So, use + # python's "thread", which is actually a single process, using + # an internal schedule to switch between tasks. No performance + # gains for non-IO tasks, but still it can be quickly interrup= ted + # from time to time to display progress. + executor =3D futures.ThreadPoolExecutor + + not_found =3D [] + f_list =3D [] + with executor(max_workers=3Dmax_workers) as exe: + for refs in self.get_fileref(all_refs, chunk_size): + if refs: + try: + f_list.append(exe.submit(self.check_file, refs, fo= und)) + + except KeyboardInterrupt: + return + + total =3D len(f_list) + + if not total: + if self.abi.re_string: + print(f"No ABI symbol matches {self.abi.search_string}= ") + else: + self.abi.log.warning("No ABI symbols found") + return + + print(f"{len(f_list):6d} jobs queued on {max_workers} workers", + file=3Dsys.stderr) + + while f_list: + try: + t =3D futures.wait(f_list, timeout=3D1, + return_when=3Dfutures.FIRST_COMPLETED) + + done =3D t[0] + + for fut in done: + res_list =3D fut.result() + + for res in res_list: + if not res["found"]: + not_found.append(res["fname"]) + if res["msg"]: + print(res["msg"]) + + f_list.remove(fut) + except KeyboardInterrupt: + return + + except RuntimeError as e: + self.abi.log.warning(f"Future: {e}") + break + + if sys.stderr.isatty(): + elapsed =3D str(datetime.now() - start).split(".", max= split=3D1)[0] + if len(f_list) < total: + elapsed +=3D f" ({total - len(f_list)}/{total} job= s completed). " + if elapsed !=3D old_elapsed: + print(elapsed + "\r", end=3D"", flush=3DTrue, + file=3Dsys.stderr) + old_elapsed =3D elapsed + + elapsed =3D str(datetime.now() - start).split(".", maxsplit=3D1)[0] + print(elapsed, file=3Dsys.stderr) + + for f in sorted(not_found): + print(f"{f} not found.") + + +REST_DESC =3D """ +Produce output in ReST format. + +The output is done on two sections: + +- Symbols: show all parsed symbols in alphabetic order; +- Files: cross reference the content of each file with the symbols on it. +""" + + class AbiRest: """Initialize an argparse subparser for rest output""" =20 @@ -725,6 +1327,71 @@ class AbiSearch: parser.parse_abi() parser.search_symbols(args.expression) =20 +UNDEFINED_DESC=3D""" +Check undefined ABIs on local machine. + +Read sysfs devnodes and check if the devnodes there are defined inside +ABI documentation. + +The search logic tries to minimize the number of regular expressions to +search per each symbol. + +By default, it runs on a single CPU, as Python support for CPU threads +is still experimental, and multi-process runs on Python is very slow. + +On experimental tests, if the number of ABI symbols to search per devnode +is contained on a limit of ~150 regular expressions, using a single CPU +is a lot faster than using multiple processes. However, if the number of +regular expressions to check is at the order of ~30000, using multiple +CPUs speeds up the check. +""" + +class AbiUndefined: + """ + Initialize an argparse subparser for logic to check undefined ABI at + the current machine's sysfs + """ + + def __init__(self, subparsers): + """Initialize argparse subparsers""" + + parser =3D subparsers.add_parser("undefined", + formatter_class=3Dargparse.RawTextH= elpFormatter, + description=3DUNDEFINED_DESC) + + parser.add_argument("-S", "--sysfs-dir", default=3D"/sys", + help=3D"directory where sysfs is mounted") + parser.add_argument("-s", "--search-string", + help=3D"search string regular expression to li= mit symbol search") + parser.add_argument("-H", "--show-hints", action=3D"store_true", + help=3D"Hints about definitions for missing AB= I symbols.") + parser.add_argument("-j", "--jobs", "--max-workers", type=3Dint, d= efault=3D1, + help=3D"If bigger than one, enables multiproce= ssing.") + parser.add_argument("-c", "--max-chunk-size", type=3Dint, default= =3D50, + help=3D"Maximum number of chunk size") + parser.add_argument("-f", "--found", action=3D"store_true", + help=3D"Also show found items. " + "Helpful to debug the parser."), + parser.add_argument("-d", "--dry-run", action=3D"store_true", + help=3D"Don't actually search for undefined. " + "Helpful to debug the parser."), + + parser.set_defaults(func=3Dself.run) + + def run(self, args): + """Run subparser""" + + abi =3D AbiRegex(args.dir, debug=3Dargs.debug, + search_string=3Dargs.search_string) + + abi_symbols =3D SystemSymbols(abi=3Dabi, hints=3Dargs.show_hints, + sysfs=3Dargs.sysfs_dir) + + abi_symbols.check_undefined_symbols(dry_run=3Dargs.dry_run, + found=3Dargs.found, + max_workers=3Dargs.jobs, + chunk_size=3Dargs.max_chunk_si= ze) + =20 def main(): """Main program""" @@ -739,6 +1406,7 @@ def main(): AbiRest(subparsers) AbiValidate(subparsers) AbiSearch(subparsers) + AbiUndefined(subparsers) =20 args =3D parser.parse_args() =20 --=20 2.48.1 From nobody Tue Dec 16 22:10:39 2025 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 E06C13207; Tue, 28 Jan 2025 00:06:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022798; cv=none; b=GWLGbtTPsDlks1IurdL2ZARocRr5BYFMwNIjL9zaiEUlgSSSfxkNCXIZeQu2aEHtUmNHtqWqo/G/LQasPOgUavDQUNwyiDAYnSPvYfmDzT1Rz4PFKP9y5CudZ4c9+vyEYUHbfmymfWUFLW4AqDZaMm+XTlylWUA0QAXMlMOGpOU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1738022798; c=relaxed/simple; bh=sCuTz3zxaa3V2tY51057fBvBcrlzP04scyPpCe0UiUk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=t0cuXlkrv3HXnGuC7kx0Cnlc3Zx3NZPlmsZqPROvCjHou7NG4dQ9wwHzSgSbT0OZBE1W4cpbD2qUjVlDb4SXY685+jh8gKYjhIK3kMamN/0I7g3T1cbQa+x9MlzJCkE5qJS3SEeWH1JCu5vwJXGe72l8msjXld0RD4T48rfO4rM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=KyBflCto; 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="KyBflCto" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5F9E2C2BCC7; Tue, 28 Jan 2025 00:06:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1738022796; bh=sCuTz3zxaa3V2tY51057fBvBcrlzP04scyPpCe0UiUk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KyBflCtoOCNe1eYXQDMhv3yXKmQuzSPmPBVTr1CWm+f8LbPeJskf451A8zORT9PkA TdKUL0L/mcrrCkvUQCVGcyiI/cNH44xrIzzW4wNtDiWyBRCexU8aB4NBECHA2nRbDt hcHoSdgyxIQ7a74G2TvjKIp0NEVwwfAPfgkxVEVUG9gjrIyOyYA+Y+4UPRmWo2tcbW 4n7YdNI02h/5AVkToeqWPlKfSo7f75I8d4XHfsg1XyzZyPQemhQenyo/DYPM02lXA6 9jlyTy5lhrr5opWFEBYgokSdU8fb2Sczwu4msZ8IZ4SOYfyLtJoDQ0HDBqtOYS9nFz 4OlFCSUzE59tQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tcZ7i-0000000DRMs-2Tzs; Tue, 28 Jan 2025 01:06:34 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet , Greg Kroah-Hartman Cc: Mauro Carvalho Chehab , "Guilherme G. Piccoli" , "Mauro Carvalho Chehab" , Kees Cook , Tony Luck , bpf@vger.kernel.org, linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [RFC v2 38/38] scripts/get_abi.pl: drop now obsoleted script Date: Tue, 28 Jan 2025 01:06:27 +0100 Message-ID: <3ca485c75500cb5e004fa3bab7cd9732ecf47d18.1738020236.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" As all functionalities of it were migrated to get_abi.py, drop the now obsoleted script. Signed-off-by: Mauro Carvalho Chehab Reported-by: Akira Yokosawa --- scripts/get_abi.pl | 1103 -------------------------------------------- 1 file changed, 1103 deletions(-) delete mode 100755 scripts/get_abi.pl diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl deleted file mode 100755 index de1c0354b50c..000000000000 --- a/scripts/get_abi.pl +++ /dev/null @@ -1,1103 +0,0 @@ -#!/usr/bin/env perl -# SPDX-License-Identifier: GPL-2.0 - -BEGIN { $Pod::Usage::Formatter =3D 'Pod::Text::Termcap'; } - -use strict; -use warnings; -use utf8; -use Pod::Usage qw(pod2usage); -use Getopt::Long; -use File::Find; -use IO::Handle; -use Fcntl ':mode'; -use Cwd 'abs_path'; -use Data::Dumper; - -my $help =3D 0; -my $hint =3D 0; -my $man =3D 0; -my $debug =3D 0; -my $enable_lineno =3D 0; -my $show_warnings =3D 1; -my $prefix=3D"Documentation/ABI"; -my $sysfs_prefix=3D"/sys"; -my $search_string; - -# Debug options -my $dbg_what_parsing =3D 1; -my $dbg_what_open =3D 2; -my $dbg_dump_abi_structs =3D 4; -my $dbg_undefined =3D 8; - -$Data::Dumper::Indent =3D 1; -$Data::Dumper::Terse =3D 1; - -# -# If true, assumes that the description is formatted with ReST -# -my $description_is_rst =3D 1; - -GetOptions( - "debug=3Di" =3D> \$debug, - "enable-lineno" =3D> \$enable_lineno, - "rst-source!" =3D> \$description_is_rst, - "dir=3Ds" =3D> \$prefix, - 'help|?' =3D> \$help, - "show-hints" =3D> \$hint, - "search-string=3Ds" =3D> \$search_string, - man =3D> \$man -) or pod2usage(2); - -pod2usage(1) if $help; -pod2usage(-exitstatus =3D> 0, -noperldoc, -verbose =3D> 2) if $man; - -pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2); - -my ($cmd, $arg) =3D @ARGV; - -pod2usage(2) if ($cmd ne "search" && $cmd ne "rest" && $cmd ne "validate" = && $cmd ne "undefined"); -pod2usage(2) if ($cmd eq "search" && !$arg); - -require Data::Dumper if ($debug & $dbg_dump_abi_structs); - -my %data; -my %symbols; - -# -# Displays an error message, printing file name and line -# -sub parse_error($$$$) { - my ($file, $ln, $msg, $data) =3D @_; - - return if (!$show_warnings); - - $data =3D~ s/\s+$/\n/; - - print STDERR "Warning: file $file#$ln:\n\t$msg"; - - if ($data ne "") { - print STDERR ". Line\n\t\t$data"; - } else { - print STDERR "\n"; - } -} - -# -# Parse an ABI file, storing its contents at %data -# -sub parse_abi { - my $file =3D $File::Find::name; - - my $mode =3D (stat($file))[2]; - return if ($mode & S_IFDIR); - return if ($file =3D~ m,/README,); - return if ($file =3D~ m,/\.,); - return if ($file =3D~ m,\.(rej|org|orig|bak)$,); - - my $name =3D $file; - $name =3D~ s,.*/,,; - - my $fn =3D $file; - $fn =3D~ s,.*Documentation/ABI/,,; - - my $nametag =3D "File $fn"; - $data{$nametag}->{what} =3D "File $name"; - $data{$nametag}->{type} =3D "File"; - $data{$nametag}->{file} =3D $name; - $data{$nametag}->{filepath} =3D $file; - $data{$nametag}->{is_file} =3D 1; - $data{$nametag}->{line_no} =3D 1; - - my $type =3D $file; - $type =3D~ s,.*/(.*)/.*,$1,; - - my $what; - my $new_what; - my $tag =3D ""; - my $ln; - my $xrefs; - my $space; - my @labels; - my $label =3D ""; - - print STDERR "Opening $file\n" if ($debug & $dbg_what_open); - open IN, $file; - while() { - $ln++; - if (m/^(\S+)(:\s*)(.*)/i) { - my $new_tag =3D lc($1); - my $sep =3D $2; - my $content =3D $3; - - if (!($new_tag =3D~ m/(what|where|date|kernelversion|contact|descriptio= n|users)/)) { - if ($tag eq "description") { - # New "tag" is actually part of - # description. Don't consider it a tag - $new_tag =3D ""; - } elsif ($tag ne "") { - parse_error($file, $ln, "tag '$tag' is invalid", $_); - } - } - - # Invalid, but it is a common mistake - if ($new_tag eq "where") { - parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' ins= tead", ""); - $new_tag =3D "what"; - } - - if ($new_tag =3D~ m/what/) { - $space =3D ""; - $content =3D~ s/[,.;]$//; - - push @{$symbols{$content}->{file}}, " $file:" . ($ln - 1); - - if ($tag =3D~ m/what/) { - $what .=3D "\xac" . $content; - } else { - if ($what) { - parse_error($file, $ln, "What '$what' doesn't have a description", "= ") if (!$data{$what}->{description}); - - foreach my $w(split /\xac/, $what) { - $symbols{$w}->{xref} =3D $what; - }; - } - - $what =3D $content; - $label =3D $content; - $new_what =3D 1; - } - push @labels, [($content, $label)]; - $tag =3D $new_tag; - - push @{$data{$nametag}->{symbols}}, $content if ($data{$nametag}->{wha= t}); - next; - } - - if ($tag ne "" && $new_tag) { - $tag =3D $new_tag; - - if ($new_what) { - @{$data{$what}->{label_list}} =3D @labels if ($data{$nametag}->{what}= ); - @labels =3D (); - $label =3D ""; - $new_what =3D 0; - - $data{$what}->{type} =3D $type; - if (!defined($data{$what}->{file})) { - $data{$what}->{file} =3D $name; - $data{$what}->{filepath} =3D $file; - } else { - $data{$what}->{description} .=3D "\n\n" if (defined($data{$what}->{d= escription})); - if ($name ne $data{$what}->{file}) { - $data{$what}->{file} .=3D " " . $name; - $data{$what}->{filepath} .=3D " " . $file; - } - } - print STDERR "\twhat: $what\n" if ($debug & $dbg_what_parsing); - $data{$what}->{line_no} =3D $ln; - } else { - $data{$what}->{line_no} =3D $ln if (!defined($data{$what}->{line_no})= ); - } - - if (!$what) { - parse_error($file, $ln, "'What:' should come first:", $_); - next; - } - if ($new_tag eq "description") { - $sep =3D~ s,:, ,; - $content =3D ' ' x length($new_tag) . $sep . $content; - while ($content =3D~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e)= {} - if ($content =3D~ m/^(\s*)(\S.*)$/) { - # Preserve initial spaces for the first line - $space =3D $1; - $content =3D "$2\n"; - $data{$what}->{$tag} .=3D $content; - } else { - undef($space); - } - - } else { - $data{$what}->{$tag} =3D $content; - } - next; - } - } - - # Store any contents before tags at the database - if (!$tag && $data{$nametag}->{what}) { - $data{$nametag}->{description} .=3D $_; - next; - } - - if ($tag eq "description") { - my $content =3D $_; - while ($content =3D~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} - if (m/^\s*\n/) { - $data{$what}->{$tag} .=3D "\n"; - next; - } - - if (!defined($space)) { - # Preserve initial spaces for the first line - if ($content =3D~ m/^(\s*)(\S.*)$/) { - $space =3D $1; - $content =3D "$2\n"; - } - } else { - $space =3D "" if (!($content =3D~ s/^($space)//)); - } - $data{$what}->{$tag} .=3D $content; - - next; - } - if (m/^\s*(.*)/) { - $data{$what}->{$tag} .=3D "\n$1"; - $data{$what}->{$tag} =3D~ s/\n+$//; - next; - } - - # Everything else is error - parse_error($file, $ln, "Unexpected content", $_); - } - $data{$nametag}->{description} =3D~ s/^\n+// if ($data{$nametag}->{descri= ption}); - if ($what) { - parse_error($file, $ln, "What '$what' doesn't have a description", "") i= f (!$data{$what}->{description}); - - foreach my $w(split /\xac/,$what) { - $symbols{$w}->{xref} =3D $what; - }; - } - close IN; -} - -sub create_labels { - my %labels; - - foreach my $what (keys %data) { - next if ($data{$what}->{file} eq "File"); - - foreach my $p (@{$data{$what}->{label_list}}) { - my ($content, $label) =3D @{$p}; - $label =3D "abi_" . $label . " "; - $label =3D~ tr/A-Z/a-z/; - - # Convert special chars to "_" - $label =3D~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g; - $label =3D~ s,_+,_,g; - $label =3D~ s,_$,,; - - # Avoid duplicated labels - while (defined($labels{$label})) { - my @chars =3D ("A".."Z", "a".."z"); - $label .=3D $chars[rand @chars]; - } - $labels{$label} =3D 1; - - $data{$what}->{label} =3D $label; - - # only one label is enough - last; - } - } -} - -# -# Outputs the book on ReST format -# - -# \b doesn't work well with paths. So, we need to define something else: -# Boundaries are punct characters, spaces and end-of-line -my $start =3D qr {(^|\s|\() }x; -my $bondary =3D qr { ([,.:;\)\s]|\z) }x; -my $xref_match =3D qr { $start(\/(sys|config|proc|dev|kvd)\/[^,.:;\)\s]+)$= bondary }x; -my $symbols =3D qr { ([\x01-\x08\x0e-\x1f\x21-\x2f\x3a-\x40\x7b-\xff]) }x; - -sub output_rest { - create_labels(); - - my $part =3D ""; - - foreach my $what (sort { - ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") || - $a cmp $b - } keys %data) { - my $type =3D $data{$what}->{type}; - - my @file =3D split / /, $data{$what}->{file}; - my @filepath =3D split / /, $data{$what}->{filepath}; - - if ($enable_lineno) { - printf ".. LINENO %s%s#%s\n\n", - $prefix, $file[0], - $data{$what}->{line_no}; - } - - my $w =3D $what; - - if ($type ne "File") { - my $cur_part =3D $what; - if ($what =3D~ '/') { - if ($what =3D~ m#^(\/?(?:[\w\-]+\/?){1,2})#) { - $cur_part =3D "Symbols under $1"; - $cur_part =3D~ s,/$,,; - } - } - - if ($cur_part ne "" && $part ne $cur_part) { - $part =3D $cur_part; - my $bar =3D $part; - $bar =3D~ s/./-/g; - print "$part\n$bar\n\n"; - } - - printf ".. _%s:\n\n", $data{$what}->{label}; - - my @names =3D split /\xac/,$w; - my $len =3D 0; - - foreach my $name (@names) { - $name =3D~ s/$symbols/\\$1/g; - $name =3D "**$name**"; - $len =3D length($name) if (length($name) > $len); - } - - print "+-" . "-" x $len . "-+\n"; - foreach my $name (@names) { - printf "| %s", $name . " " x ($len - length($name)) . " |\n"; - print "+-" . "-" x $len . "-+\n"; - } - - print "\n"; - } - - for (my $i =3D 0; $i < scalar(@filepath); $i++) { - my $path =3D $filepath[$i]; - my $f =3D $file[$i]; - - $path =3D~ s,.*/(.*/.*),$1,;; - $path =3D~ s,[/\-],_,g;; - my $fileref =3D "abi_file_".$path; - - if ($type eq "File") { - print ".. _$fileref:\n\n"; - } else { - print "Defined on file :ref:`$f <$fileref>`\n\n"; - } - } - - if ($type eq "File") { - my $bar =3D $w; - $bar =3D~ s/./-/g; - print "$w\n$bar\n\n"; - } - - my $desc =3D ""; - $desc =3D $data{$what}->{description} if (defined($data{$what}->{descrip= tion})); - $desc =3D~ s/\s+$/\n/; - - if (!($desc =3D~ /^\s*$/)) { - if ($description_is_rst) { - # Remove title markups from the description - # Having titles inside ABI files will only work if extra - # care would be taken in order to strictly follow the same - # level order for each markup. - $desc =3D~ s/\n[\-\*\=3D\^\~]+\n/\n\n/g; - - # Enrich text by creating cross-references - - my $new_desc =3D ""; - my $init_indent =3D -1; - my $literal_indent =3D -1; - - open(my $fh, "+<", \$desc); - while (my $d =3D <$fh>) { - my $indent =3D $d =3D~ m/^(\s+)/; - my $spaces =3D length($indent); - $init_indent =3D $indent if ($init_indent < 0); - if ($literal_indent >=3D 0) { - if ($spaces > $literal_indent) { - $new_desc .=3D $d; - next; - } else { - $literal_indent =3D -1; - } - } else { - if ($d =3D~ /()::$/ && !($d =3D~ /^\s*\.\./)) { - $literal_indent =3D $spaces; - } - } - - $d =3D~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g; - - my @matches =3D $d =3D~ m,Documentation/ABI/([\w\/\-]+),g; - foreach my $f (@matches) { - my $xref =3D $f; - my $path =3D $f; - $path =3D~ s,.*/(.*/.*),$1,;; - $path =3D~ s,[/\-],_,g;; - $xref .=3D " "; - $d =3D~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g; - } - - # Seek for cross reference symbols like /sys/... - @matches =3D $d =3D~ m/$xref_match/g; - - foreach my $s (@matches) { - next if (!($s =3D~ m,/,)); - if (defined($data{$s}) && defined($data{$s}->{label})) { - my $xref =3D $s; - - $xref =3D~ s/$symbols/\\$1/g; - $xref =3D ":ref:`$xref <" . $data{$s}->{label} . ">`"; - - $d =3D~ s,$start$s$bondary,$1$xref$2,g; - } - } - $new_desc .=3D $d; - } - close $fh; - - - print "$new_desc\n\n"; - } else { - $desc =3D~ s/^\s+//; - - # Remove title markups from the description, as they won't work - $desc =3D~ s/\n[\-\*\=3D\^\~]+\n/\n\n/g; - - if ($desc =3D~ m/\:\n/ || $desc =3D~ m/\n[\t ]+/ || $desc =3D~ m/[\x0= 0-\x08\x0b-\x1f\x7b-\xff]/) { - # put everything inside a code block - $desc =3D~ s/\n/\n /g; - - print "::\n\n"; - print " $desc\n\n"; - } else { - # Escape any special chars from description - $desc =3D~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x= 60\x7b-\xff])/\\$1/g; - print "$desc\n\n"; - } - } - } else { - print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file}); - } - - if ($data{$what}->{symbols}) { - printf "Has the following ABI:\n\n"; - - foreach my $content(@{$data{$what}->{symbols}}) { - my $label =3D $data{$symbols{$content}->{xref}}->{label}; - - # Escape special chars from content - $content =3D~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; - - print "- :ref:`$content <$label>`\n\n"; - } - } - - if (defined($data{$what}->{users})) { - my $users =3D $data{$what}->{users}; - - $users =3D~ s/\n/\n\t/g; - printf "Users:\n\t%s\n\n", $users if ($users ne ""); - } - - } -} - -# -# Searches for ABI symbols -# -sub search_symbols { - foreach my $what (sort keys %data) { - next if (!($what =3D~ m/($arg)/)); - - my $type =3D $data{$what}->{type}; - next if ($type eq "File"); - - my $file =3D $data{$what}->{filepath}; - - $what =3D~ s/\xac/, /g; - my $bar =3D $what; - $bar =3D~ s/./-/g; - - print "\n$what\n$bar\n\n"; - - my $kernelversion =3D $data{$what}->{kernelversion} if (defined($data{$w= hat}->{kernelversion})); - my $contact =3D $data{$what}->{contact} if (defined($data{$what}->{conta= ct})); - my $users =3D $data{$what}->{users} if (defined($data{$what}->{users})); - my $date =3D $data{$what}->{date} if (defined($data{$what}->{date})); - my $desc =3D $data{$what}->{description} if (defined($data{$what}->{desc= ription})); - - $kernelversion =3D~ s/^\s+// if ($kernelversion); - $contact =3D~ s/^\s+// if ($contact); - if ($users) { - $users =3D~ s/^\s+//; - $users =3D~ s/\n//g; - } - $date =3D~ s/^\s+// if ($date); - $desc =3D~ s/^\s+// if ($desc); - - printf "Kernel version:\t\t%s\n", $kernelversion if ($kernelversion); - printf "Date:\t\t\t%s\n", $date if ($date); - printf "Contact:\t\t%s\n", $contact if ($contact); - printf "Users:\t\t\t%s\n", $users if ($users); - print "Defined on file(s):\t$file\n\n"; - print "Description:\n\n$desc"; - } -} - -# Exclude /sys/kernel/debug and /sys/kernel/tracing from the search path -sub dont_parse_special_attributes { - if (($File::Find::dir =3D~ m,^/sys/kernel,)) { - return grep {!/(debug|tracing)/ } @_; - } - - if (($File::Find::dir =3D~ m,^/sys/fs,)) { - return grep {!/(pstore|bpf|fuse)/ } @_; - } - - return @_ -} - -my %leaf; -my %aliases; -my @files; -my %root; - -sub graph_add_file { - my $file =3D shift; - my $type =3D shift; - - my $dir =3D $file; - $dir =3D~ s,^(.*/).*,$1,; - $file =3D~ s,.*/,,; - - my $name; - my $file_ref =3D \%root; - foreach my $edge(split "/", $dir) { - $name .=3D "$edge/"; - if (!defined ${$file_ref}{$edge}) { - ${$file_ref}{$edge} =3D { }; - } - $file_ref =3D \%{$$file_ref{$edge}}; - ${$file_ref}{"__name"} =3D [ $name ]; - } - $name .=3D "$file"; - ${$file_ref}{$file} =3D { - "__name" =3D> [ $name ] - }; - - return \%{$$file_ref{$file}}; -} - -sub graph_add_link { - my $file =3D shift; - my $link =3D shift; - - # Traverse graph to find the reference - my $file_ref =3D \%root; - foreach my $edge(split "/", $file) { - $file_ref =3D \%{$$file_ref{$edge}} || die "Missing node!"; - } - - # do a BFS - - my @queue; - my %seen; - my $st; - - push @queue, $file_ref; - $seen{$start}++; - - while (@queue) { - my $v =3D shift @queue; - my @child =3D keys(%{$v}); - - foreach my $c(@child) { - next if $seen{$$v{$c}}; - next if ($c eq "__name"); - - if (!defined($$v{$c}{"__name"})) { - printf STDERR "Error: Couldn't find a non-empty name on a children of = $file/.*: "; - print STDERR Dumper(%{$v}); - exit; - } - - # Add new name - my $name =3D @{$$v{$c}{"__name"}}[0]; - if ($name =3D~ s#^$file/#$link/#) { - push @{$$v{$c}{"__name"}}, $name; - } - # Add child to the queue and mark as seen - push @queue, $$v{$c}; - $seen{$c}++; - } - } -} - -my $escape_symbols =3D qr { ([\x01-\x08\x0e-\x1f\x21-\x29\x2b-\x2d\x3a-\x4= 0\x7b-\xfe]) }x; -sub parse_existing_sysfs { - my $file =3D $File::Find::name; - - my $mode =3D (lstat($file))[2]; - my $abs_file =3D abs_path($file); - - my @tmp; - push @tmp, $file; - push @tmp, $abs_file if ($abs_file ne $file); - - foreach my $f(@tmp) { - # Ignore cgroup, as this is big and has zero docs under ABI - return if ($f =3D~ m#^/sys/fs/cgroup/#); - - # Ignore firmware as it is documented elsewhere - # Either ACPI or under Documentation/devicetree/bindings/ - return if ($f =3D~ m#^/sys/firmware/#); - - # Ignore some sysfs nodes that aren't actually part of ABI - return if ($f =3D~ m#/sections|notes/#); - - # Would need to check at - # Documentation/admin-guide/kernel-parameters.txt, but this - # is not easily parseable. - return if ($f =3D~ m#/parameters/#); - } - - if (S_ISLNK($mode)) { - $aliases{$file} =3D $abs_file; - return; - } - - return if (S_ISDIR($mode)); - - # Trivial: file is defined exactly the same way at ABI What: - return if (defined($data{$file})); - return if (defined($data{$abs_file})); - - push @files, graph_add_file($abs_file, "file"); -} - -sub get_leave($) -{ - my $what =3D shift; - my $leave; - - my $l =3D $what; - my $stop =3D 1; - - $leave =3D $l; - $leave =3D~ s,/$,,; - $leave =3D~ s,.*/,,; - $leave =3D~ s/[\(\)]//g; - - # $leave is used to improve search performance at - # check_undefined_symbols, as the algorithm there can seek - # for a small number of "what". It also allows giving a - # hint about a leave with the same name somewhere else. - # However, there are a few occurences where the leave is - # either a wildcard or a number. Just group such cases - # altogether. - if ($leave =3D~ m/\.\*/ || $leave eq "" || $leave =3D~ /\\d/) { - $leave =3D "others"; - } - - return $leave; -} - -my @not_found; - -sub check_file($$) -{ - my $file_ref =3D shift; - my $names_ref =3D shift; - my @names =3D @{$names_ref}; - my $file =3D $names[0]; - - my $found_string; - - my $leave =3D get_leave($file); - if (!defined($leaf{$leave})) { - $leave =3D "others"; - } - my @expr =3D @{$leaf{$leave}->{expr}}; - die ("\rmissing rules for $leave") if (!defined($leaf{$leave})); - - my $path =3D $file; - $path =3D~ s,(.*/).*,$1,; - - if ($search_string) { - return if (!($file =3D~ m#$search_string#)); - $found_string =3D 1; - } - - for (my $i =3D 0; $i < @names; $i++) { - if ($found_string && $hint) { - if (!$i) { - print STDERR "--> $names[$i]\n"; - } else { - print STDERR " $names[$i]\n"; - } - } - foreach my $re (@expr) { - print STDERR "$names[$i] =3D~ /^$re\$/\n" if ($debug && $dbg_undefined); - if ($names[$i] =3D~ $re) { - return; - } - } - } - - if ($leave ne "others") { - my @expr =3D @{$leaf{"others"}->{expr}}; - for (my $i =3D 0; $i < @names; $i++) { - foreach my $re (@expr) { - print STDERR "$names[$i] =3D~ /^$re\$/\n" if ($debug && $dbg_undefined= ); - if ($names[$i] =3D~ $re) { - return; - } - } - } - } - - push @not_found, $file if (!$search_string || $found_string); - - if ($hint && (!$search_string || $found_string)) { - my $what =3D $leaf{$leave}->{what}; - $what =3D~ s/\xac/\n\t/g; - if ($leave ne "others") { - print STDERR "\r more likely regexes:\n\t$what\n"; - } else { - print STDERR "\r tested regexes:\n\t$what\n"; - } - } -} - -sub check_undefined_symbols { - my $num_files =3D scalar @files; - my $next_i =3D 0; - my $start_time =3D times; - - @files =3D sort @files; - - my $last_time =3D $start_time; - - # When either debug or hint is enabled, there's no sense showing - # progress, as the progress will be overriden. - if ($hint || ($debug && $dbg_undefined)) { - $next_i =3D $num_files; - } - - my $is_console; - $is_console =3D 1 if (-t STDERR); - - for (my $i =3D 0; $i < $num_files; $i++) { - my $file_ref =3D $files[$i]; - my @names =3D @{$$file_ref{"__name"}}; - - check_file($file_ref, \@names); - - my $cur_time =3D times; - - if ($i =3D=3D $next_i || $cur_time > $last_time + 1) { - my $percent =3D $i * 100 / $num_files; - - my $tm =3D $cur_time - $start_time; - my $time =3D sprintf "%d:%02d", int($tm), 60 * ($tm - int($tm)); - - printf STDERR "\33[2K\r", if ($is_console); - printf STDERR "%s: processing sysfs files... %i%%: $names[0]", $time, $= percent; - printf STDERR "\n", if (!$is_console); - STDERR->flush(); - - $next_i =3D int (($percent + 1) * $num_files / 100); - $last_time =3D $cur_time; - } - } - - my $cur_time =3D times; - my $tm =3D $cur_time - $start_time; - my $time =3D sprintf "%d:%02d", int($tm), 60 * ($tm - int($tm)); - - printf STDERR "\33[2K\r", if ($is_console); - printf STDERR "%s: processing sysfs files... done\n", $time; - - foreach my $file (@not_found) { - print "$file not found.\n"; - } -} - -sub undefined_symbols { - print STDERR "Reading $sysfs_prefix directory contents..."; - find({ - wanted =3D>\&parse_existing_sysfs, - preprocess =3D>\&dont_parse_special_attributes, - no_chdir =3D> 1 - }, $sysfs_prefix); - print STDERR "done.\n"; - - $leaf{"others"}->{what} =3D ""; - - print STDERR "Converting ABI What fields into regexes..."; - foreach my $w (sort keys %data) { - foreach my $what (split /\xac/,$w) { - next if (!($what =3D~ m/^$sysfs_prefix/)); - - # Convert what into regular expressions - - # Escape dot characters - $what =3D~ s/\./\xf6/g; - - # Temporarily change [0-9]+ type of patterns - $what =3D~ s/\[0\-9\]\+/\xff/g; - - # Temporarily change [\d+-\d+] type of patterns - $what =3D~ s/\[0\-\d+\]/\xff/g; - $what =3D~ s/\[(\d+)\]/\xf4$1\xf5/g; - - # Temporarily change [0-9] type of patterns - $what =3D~ s/\[(\d)\-(\d)\]/\xf4$1-$2\xf5/g; - - # Handle multiple option patterns - $what =3D~ s/[\{\<\[]([\w_]+)(?:[,|]+([\w_]+)){1,}[\}\>\]]/($1|$2)/g; - - # Handle wildcards - $what =3D~ s,\*,.*,g; - $what =3D~ s,/\xf6..,/.*,g; - $what =3D~ s/\<[^\>]+\>/.*/g; - $what =3D~ s/\{[^\}]+\}/.*/g; - $what =3D~ s/\[[^\]]+\]/.*/g; - - $what =3D~ s/[XYZ]/.*/g; - - # Recover [0-9] type of patterns - $what =3D~ s/\xf4/[/g; - $what =3D~ s/\xf5/]/g; - - # Remove duplicated spaces - $what =3D~ s/\s+/ /g; - - # Special case: this ABI has a parenthesis on it - $what =3D~ s/sqrt\(x^2\+y^2\+z^2\)/sqrt\(x^2\+y^2\+z^2\)/; - - # Special case: drop comparition as in: - # What: foo =3D - # (this happens on a few IIO definitions) - $what =3D~ s,\s*\=3D.*$,,; - - # Escape all other symbols - $what =3D~ s/$escape_symbols/\\$1/g; - $what =3D~ s/\\\\/\\/g; - $what =3D~ s/\\([\[\]\(\)\|])/$1/g; - $what =3D~ s/(\d+)\\(-\d+)/$1$2/g; - - $what =3D~ s/\xff/\\d+/g; - - # Special case: IIO ABI which a parenthesis. - $what =3D~ s/sqrt(.*)/sqrt\(.*\)/; - - # Simplify regexes with multiple .* - $what =3D~ s#(?:\.\*){2,}##g; -# $what =3D~ s#\.\*/\.\*#.*#g; - - # Recover dot characters - $what =3D~ s/\xf6/\./g; - - my $leave =3D get_leave($what); - - my $added =3D 0; - foreach my $l (split /\|/, $leave) { - if (defined($leaf{$l})) { - next if ($leaf{$l}->{what} =3D~ m/\b$what\b/); - $leaf{$l}->{what} .=3D "\xac" . $what; - $added =3D 1; - } else { - $leaf{$l}->{what} =3D $what; - $added =3D 1; - } - } - if ($search_string && $added) { - print STDERR "What: $what\n" if ($what =3D~ m#$search_string#); - } - - } - } - # Compile regexes - foreach my $l (sort keys %leaf) { - my @expr; - foreach my $w(sort split /\xac/, $leaf{$l}->{what}) { - push @expr, qr /^$w$/; - } - $leaf{$l}->{expr} =3D \@expr; - } - - # Take links into account - foreach my $link (sort keys %aliases) { - my $abs_file =3D $aliases{$link}; - graph_add_link($abs_file, $link); - } - print STDERR "done.\n"; - - check_undefined_symbols; -} - -# Ensure that the prefix will always end with a slash -# While this is not needed for find, it makes the patch nicer -# with --enable-lineno -$prefix =3D~ s,/?$,/,; - -if ($cmd eq "undefined" || $cmd eq "search") { - $show_warnings =3D 0; -} -# -# Parses all ABI files located at $prefix dir -# -find({wanted =3D>\&parse_abi, no_chdir =3D> 1}, $prefix); - -print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug & $dbg_d= ump_abi_structs); - -# -# Handles the command -# -if ($cmd eq "undefined") { - undefined_symbols; -} elsif ($cmd eq "search") { - search_symbols; -} else { - if ($cmd eq "rest") { - output_rest; - } - - # Warn about duplicated ABI entries - foreach my $what(sort keys %symbols) { - my @files =3D @{$symbols{$what}->{file}}; - - next if (scalar(@files) =3D=3D 1); - - printf STDERR "Warning: $what is defined %d times: @files\n", - scalar(@files); - } -} - -__END__ - -=3Dhead1 NAME - -get_abi.pl - parse the Linux ABI files and produce a ReST book. - -=3Dhead1 SYNOPSIS - -B [--debug ] [--enable-lineno] [--man] [--help] - [--(no-)rst-source] [--dir=3D] [--show-hints] - [--search-string ] - [] - -Where B can be: - -=3Dover 8 - -B I - search for I inside ABI - -B - output the ABI in ReST markup language - -B - validate the ABI contents - -B - existing symbols at the system that aren't - defined at Documentation/ABI - -=3Dback - -=3Dhead1 OPTIONS - -=3Dover 8 - -=3Ditem B<--dir> - -Changes the location of the ABI search. By default, it uses -the Documentation/ABI directory. - -=3Ditem B<--rst-source> and B<--no-rst-source> - -The input file may be using ReST syntax or not. Those two options allow -selecting between a rst-compliant source ABI (B<--rst-source>), or a -plain text that may be violating ReST spec, so it requres some escaping -logic (B<--no-rst-source>). - -=3Ditem B<--enable-lineno> - -Enable output of .. LINENO lines. - -=3Ditem B<--debug> I - -Print debug information according with the level, which is given by the -following bitmask: - - - 1: Debug parsing What entries from ABI files; - - 2: Shows what files are opened from ABI files; - - 4: Dump the structs used to store the contents of the ABI files. - -=3Ditem B<--show-hints> - -Show hints about possible definitions for the missing ABI symbols. -Used only when B. - -=3Ditem B<--search-string> I - -Show only occurences that match a search string. -Used only when B. - -=3Ditem B<--help> - -Prints a brief help message and exits. - -=3Ditem B<--man> - -Prints the manual page and exits. - -=3Dback - -=3Dhead1 DESCRIPTION - -Parse the Linux ABI files from ABI DIR (usually located at Documentation/A= BI), -allowing to search for ABI symbols or to produce a ReST book containing -the Linux ABI documentation. - -=3Dhead1 EXAMPLES - -Search for all stable symbols with the word "usb": - -=3Dover 8 - -$ scripts/get_abi.pl search usb --dir Documentation/ABI/stable - -=3Dback - -Search for all symbols that match the regex expression "usb.*cap": - -=3Dover 8 - -$ scripts/get_abi.pl search usb.*cap - -=3Dback - -Output all obsoleted symbols in ReST format - -=3Dover 8 - -$ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete - -=3Dback - -=3Dhead1 BUGS - -Report bugs to Mauro Carvalho Chehab - -=3Dhead1 COPYRIGHT - -Copyright (c) 2016-2021 by Mauro Carvalho Chehab . - -License GPLv2: GNU GPL version 2 . - -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. - -=3Dcut --=20 2.48.1