From patchwork Mon Feb 10 10:17:49 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 13967575 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.sourceforge.net (lists.sourceforge.net [216.105.38.7]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 3EA5FC02198 for ; Mon, 10 Feb 2025 10:18:38 +0000 (UTC) Received: from [127.0.0.1] (helo=sfs-ml-2.v29.lw.sourceforge.com) by sfs-ml-2.v29.lw.sourceforge.com with esmtp (Exim 4.95) (envelope-from ) id 1thQs9-0003yq-36; Mon, 10 Feb 2025 10:18:37 +0000 Received: from [172.30.29.66] (helo=mx.sourceforge.net) by sfs-ml-2.v29.lw.sourceforge.com with esmtps (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.95) (envelope-from ) id 1thQs6-0003yV-M4 for linux-f2fs-devel@lists.sourceforge.net; Mon, 10 Feb 2025 10:18:35 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sourceforge.net; s=x; h=Sender:Content-Transfer-Encoding:MIME-Version: Message-ID:Date:Subject:Cc:To:From:Reply-To:Content-Type:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=iWu6lxVdt4DkLo8TsXZLVD2K1CQXEitCDCNfEX4Lczg=; b=Iv2BQvAjMbZOnt1ibqd2HSge3e 44lDDYQc+hI27IMBoh5faB7aBpIZiKWNrrCbG9hlZ80m/zXhpqM5xmTqyino8ohPjqPyR4BlLBr2j 8sbskgJNgnESbM+1FbxmGgsDNRx2ox4xYw6X7Qskjq+UiieW1PQHW6d1eLDKidsWF+Lw=; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sf.net; s=x ; h=Sender:Content-Transfer-Encoding:MIME-Version:Message-ID:Date:Subject:Cc: To:From:Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:In-Reply-To: References:List-Id:List-Help:List-Unsubscribe:List-Subscribe:List-Post: List-Owner:List-Archive; bh=iWu6lxVdt4DkLo8TsXZLVD2K1CQXEitCDCNfEX4Lczg=; b=g I9sqHAVmej246BwA1bqnmAF56uHLzbe1/bbb+hudhtL7vOspQYyIxTNKG+ay98bLRfa08wNWHBWr1 U/nFAdDZ7DJf256WGvQTvP+PY22Lr5/B4+yH4o4oasKk1Qf9DMMxeXiMcxksJQuhO1PhnnjC+IBQ5 gw+NfTidVuvxTAzI=; Received: from dfw.source.kernel.org ([139.178.84.217]) by sfi-mx-2.v28.lw.sourceforge.com with esmtps (TLS1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.95) id 1thQs6-00041c-H7 for linux-f2fs-devel@lists.sourceforge.net; Mon, 10 Feb 2025 10:18:35 +0000 Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by dfw.source.kernel.org (Postfix) with ESMTP id 8B88A5C48CC; Mon, 10 Feb 2025 10:17:44 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id C56D2C4CEE6; Mon, 10 Feb 2025 10:18:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1739182703; bh=p8iRm7Gznn3ekKIRR91V/psR21ij9bK+0II7DymWAjA=; h=From:To:Cc:Subject:Date:From; b=PX0+CSSljZXtmDbUPsW3q/1UEAZkcJHQHMj/eR0Q8uSPrNmrv7jqsd3H+YWo1xOM/ HjMrHdx6LlY4VekopfJmqAvseecf+sebvVrDYeBP2E4GKMMrmkGAF7v22e90DTf2Ge mjxsRdCf7qv3lINGQIUrTR/CKUR1x2WI5IgNnSnIRO7tiHp3FFc+3cqvsj/9hsWnKh QUvK4DWNq98U6G9Jmn/ZLIwMSS34I6YncKIZUQdrGDo3GiokB90neYSGG7qvgPEeX+ u8zr8PFfVeA+4pAnIe0oPCCKpjgmBbYQ3zyMgD9kNY5qkMBCxcJD7jQPVUsrPO+vlG qr78nANSqX06Q== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1thQrt-00000006Ci9-3Zgs; Mon, 10 Feb 2025 11:18:21 +0100 To: Linux Doc Mailing List Date: Mon, 10 Feb 2025 11:17:49 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 MIME-Version: 1.0 X-Headers-End: 1thQs6-00041c-H7 Subject: [f2fs-dev] [PATCH 00/27] Improve ABI documentation generation X-BeenThere: linux-f2fs-devel@lists.sourceforge.net X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Mauro Carvalho Chehab via Linux-f2fs-devel From: Mauro Carvalho Chehab Reply-To: Mauro Carvalho Chehab Cc: Tony Luck , Jonathan Corbet , Jaegeuk Kim , James Clark , Suzuki K Poulose , linux-wireless@vger.kernel.org, linux-kernel@vger.kernel.org, linux-f2fs-devel@lists.sourceforge.net, "Guilherme G. Piccoli" , linux-hardening@vger.kernel.org, coresight@lists.linaro.org, Johannes Berg , bpf@vger.kernel.org, linux-arm-kernel@lists.infradead.org, Mike Leach Errors-To: linux-f2fs-devel-bounces@lists.sourceforge.net Hi Jon/Greg, This series replace get_abi.pl with a Python version. I originally started it due to some issues I noticed when searching for ABI symbols. While I could just go ahead and fix the already existing script, I noticed that the script maintainance didn't have much care over all those years, probably because it is easier to find Python programmers those days. Also, the code is complex and was not using modules or classes and were using lots of global variables. So, I decided to rewrite it in Python. I started with a manual conversion for each function. Yet, to avoid future maintainership issues, I opted to divide the main code on three classes, each on a sepaparate file. Just like the original RFC, I opted to keep the Sphinx kernel-abi module on three different phases: - call get_abi.py as an exec file; - import AbiParser on a minimal integration scenario; - cleanup the code to avoid needing to parse line numbers from the text. This way, if something goes wrong, it would be easier to just revert any offending patches, It also provides a better rationale about what each logical change is doing. The initial patches on this series do some preparation work and cleans some ABI symbol bugs that lack ":" delimiter. I opted to place on this series the Sphinx and Python version updates. I still have ~10 patches here with additional cleanups, from the original series I sent as RFC but let's get the main changes merged first. Mauro Carvalho Chehab (27): docs: sphinx: remove kernellog.py file docs: sphinx/kernel_abi: adjust coding style docs: admin-guide: abi: add SPDX tags to ABI files ABI: sysfs-class-rfkill: fix kernelversion tags ABI: sysfs-bus-coresight-*: fix kernelversion tags ABI: sysfs-driver-dma-idxd: fix date tags ABI: sysfs-fs-f2fs: fix date tags ABI: sysfs-power: fix a what tag scripts/documentation-file-ref-check: don't check perl/python scripts scripts/get_abi.py: add a Python tool to generate ReST output scripts/get_abi.py: add support for symbol search docs: use get_abi.py for ABI generation scripts/lib/abi/abi_parser.py: optimize parse_abi() function scripts/lib/abi/abi_parser.py: use an interactor for ReST output docs: sphinx/kernel_abi: use AbiParser directly docs: sphinx/kernel_abi: reduce buffer usage for ABI messages docs: sphinx/kernel_abi: properly split lines scripts/get_abi.pl: Add filtering capabilities to rest output scripts/get_abi.pl: add support to parse ABI README file docs: sphinx/kernel_abi: parse ABI files only once docs: admin-guide/abi: split files from symbols docs: sphinx/automarkup: add cross-references for ABI docs: sphinx/kernel_abi: avoid warnings during Sphinx module init scripts/lib/abi/abi_parser.py: Rename title name for ABI files scripts/lib/abi/abi_parser.py: make it backward-compatible with Python 3.6 scripts/get_abi.py: add support for undefined ABIs scripts/get_abi.pl: drop now obsoleted script Documentation/ABI/removed/sysfs-class-rfkill | 2 +- Documentation/ABI/stable/sysfs-class-rfkill | 12 +- .../ABI/stable/sysfs-driver-dma-idxd | 4 +- .../testing/sysfs-bus-coresight-devices-cti | 78 +- .../testing/sysfs-bus-coresight-devices-tpdm | 52 +- Documentation/ABI/testing/sysfs-fs-f2fs | 4 +- Documentation/ABI/testing/sysfs-power | 2 +- .../admin-guide/abi-obsolete-files.rst | 7 + Documentation/admin-guide/abi-obsolete.rst | 6 +- Documentation/admin-guide/abi-readme-file.rst | 6 + .../admin-guide/abi-removed-files.rst | 7 + Documentation/admin-guide/abi-removed.rst | 6 +- .../admin-guide/abi-stable-files.rst | 7 + Documentation/admin-guide/abi-stable.rst | 6 +- .../admin-guide/abi-testing-files.rst | 7 + Documentation/admin-guide/abi-testing.rst | 6 +- Documentation/admin-guide/abi.rst | 17 + Documentation/sphinx/automarkup.py | 47 + Documentation/sphinx/kernel_abi.py | 162 ++- Documentation/sphinx/kerneldoc.py | 14 +- Documentation/sphinx/kernellog.py | 22 - Documentation/sphinx/kfigure.py | 81 +- scripts/documentation-file-ref-check | 2 +- scripts/get_abi.pl | 1103 ----------------- scripts/get_abi.py | 214 ++++ scripts/lib/abi/abi_parser.py | 628 ++++++++++ scripts/lib/abi/abi_regex.py | 234 ++++ scripts/lib/abi/helpers.py | 38 + scripts/lib/abi/system_symbols.py | 378 ++++++ 29 files changed, 1830 insertions(+), 1322 deletions(-) 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 delete mode 100644 Documentation/sphinx/kernellog.py delete mode 100755 scripts/get_abi.pl create mode 100755 scripts/get_abi.py create mode 100644 scripts/lib/abi/abi_parser.py create mode 100644 scripts/lib/abi/abi_regex.py create mode 100644 scripts/lib/abi/helpers.py create mode 100644 scripts/lib/abi/system_symbols.py Signed-off-by: Mauro Carvalho Chehab